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1 The Authorization Server 

1.1 Introduction 

The Authorization Server has the responsibility of authenicating a user's identity by cheeking a login name 
and password against the list of recoginzed users and their passwords. This version of the Authorization 
server is only temporary. The temporary Authorization Server runs on a remote PERQ so that if that PERQ is 
down then the Authorization Server will not be running. This Authorization Server identifies each user with 
a unique id. A user may have owner or world access privileges. This is described in the Introduction to the 
Spice User's Manual. The Authorization Server that will be implemented in the future is described in the 
Sesame: The Spice File System Manual and will include group access privileges. 

1.2 Type Definitions 

The following type are defined in Authdefs.pas. 
Auth Var.Size = 30; 

No.User =0; { files owned by "nobody" } 

First.User =1; { first valid user } 

Type 

Auth.Var = String[Auth_Var.Size]; 

User.ID = No User..Max Users; { must be "bitlO" } 

PassType = Long; { a two word value } 

{ 4 chars for a password??? } 

UserRecord = record 

Name: Auth.Var; { Name of the user } 
UserlD: User.ID; { The user ID of the user. } 
EncryptPass: PassType; { The encrypted password. } 
Profile: APath.Name; { Path name of the profile file. } 
NameOfShell: APath.Name; { Name of the ShellRUN File. } 
End; 

Machine.Name = String[255]; 

Check Type = (Check.Login, { user is logging in } 
Check.User); { user is changing parameters } 

Logged.User = record { one logged- in user } 

Use'rlD :User ID; 
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UserName :Auth_Var; 
MachineName :Auth_Var; 
End; 

Logged_User_ Array = array [0..0] of Logged.User; 
Logged.User.List = tLogged_User.Array; 

CONST 

Auth_Error_Base = 5000; 

UserNameNotFound = Auth_Error_Base + 1; 
PassWordlncorrect = Auth_Error.Ba§e + 2; 
AuthPortlncorrect = Auth_Error„Base + 3; 

13 Routines 

The following functions andprocedures are found in Authuser.pas. 

InitAuth 



Call: 

procedure InitAuth( 

RPort : Port) 

Parameters: 

RPort 

ARunLoad initializes a process address space from RunFileName (or from a run file structure in memory ifp 
is not nil), and optionally starts it executing. 
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LoginUser 

Logs a user into the authentication server. 
Call: 

procedure LoginUser( 

ServPort : Port; 
UserName : Auth _Var; 
Password : Auth_Var; 
MachineName :Auth_Var; 
var UserAuthPort : Port; * 

var UserRec : UserRecord) 
: GeneralReturn 

Parameters: 
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ServPort-The authentication server port 

UserName-thQ name of the user to check 

Passworrf^assword for the user 

MachineName 

UserAuthPort-Port returned to the user if the name and password 
match 

UserRec-ls filled with the user information if the user name and 
password match 

Success- Valid user, logged in 
other-Invalid user 
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LogoutUser 



Logs a user out 
Call: 



Parameters: 



Results: 



function LogoutUser( 

ServPort : Port) 
: GeneralReturn 



ServPort-The port for the authentication server. 
Success-AuthPortlncorrect 



ConflrmUser 

Checks the UserAuthPort to ensure that the user is logged in If so, returns useful information about the user 

Call: 

function ConfirmUser( 

ServPort : Port; 
UserAuthPort : Port; 
var Userld : User ID; 
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Parameters: 



Results: 



var UserMachineName: Auth Var) 
: GeneralReturn 



ServPort-The port for the authentication server 

UserAuthPort-thz signature port 

t/ser/D-Retums the ID number for the user 

UserMachineName-Retiirns the name for the machine that the user is 
logged on. 

Success-if the user is valid 
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CheckUser 

Verifies a user name/pasword pair and returns information about that user. 

Call: 

function CheckUser( 

ServPort : Port; 
UserName: AuthJVar; 
Password : Auth. Var; 

var UserRec : UserRecord) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-ThQ authentication server port 

UserName-usQT name to be checked 

Password-password for the user 

UserRec-ls filled with user information if the user name and 
password match. 

Success-Valid user 
ctf/ier-Invalid user 
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ChangeUserParams 



27 Aug 84 



Servers-5 



This function changes the parameters for a logged- in user. 
Call: 



Parameters: 



Results: 



function ChangeUserParams( 

ServPort : Port; 
UserName : Port; 
CurrentPassword: Auth.Var; 
ChangcPassword : Boolean; 
NewPassword: Auth _Var; 
NewProfile: APath_Name; 
NewShell : APath_Name) 
: GeneralReturn 



ServPort-The port for the user's authentication server. 
UserName-'Na.mQ of the user whose information is to be changed 
CurrentPassword-cunent password in the user's record 
ChangePassword-lf true, change password 
NewPassword-new password to replace the current one 
NewProfile-path name of the profile file for the user 
NewShell-namQ of the shell to be stored in the user record. 

Success-if the user was added or changed. 

AuthPortlncorrect-lfthQ user did not have the proper access rights to add or change 
a user. 
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GetUserName 

Gets the user name corresponding to a User ID. 

Call: 

function GetUserName( 

ServPort : Port; 
Userld : User .ID; 
var UserName: Auth_Var) 
: GeneralReluia 

Parameters: 
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Serv/'ort-Authentication Port Server 

UserlD-UserlD 

UserName-RQtums the name for the user 

Success 
UserNameNotFound 
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ListLoggedlnUsers 

Returns all of the users currently logged in to this Authentication Server. 

Call: 

function ListLoggedInUsers( 

ServPort : Port; 
varUserList : Logged JJserList; 
var UserList_Cnt: long) 
: GeneralRetura 



HHfiWH 



Parameters: 



Results: 



ServAjrt-Authentication server port 
C/serL/rt-Returns a list of user- ID-Machine 
UserList_Cnt-RQtums the number of users logged in. 

Success 
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2 The Environment Manager 

2.1 Introduction 

The Environment Manager provides a language and process independent way of sharing directory 
searchlists and other variables among different processes executing on one machine. 
The Environment Manager provides a message interface to define and retrieve environment variables. An 
environment variable is a named variable that has a type, a scope, and a set of values associated with it 
There are two types: a string- valued variable and a searchlist. The values of the variables are kept as a 
variable-length array of strings. An environment variable has a scope associated with it, either local or 
global. A local variable is seen only by a single process. The local environment of the parent is copied at 
process creation time and is passed to the child process. Once the copy is made, any subsequest changes are 
not shared between parent and child. Only global variables can be shared between processes. Global 
variables are visible to all the processes that are served by the Environment Manager. 

A String-valued variable simply allows one to store and retrieve arbitrary strings. 

A Searchlist-valued variable is a list of directories to be searched when looking for a file. The entries in a 
searchlist are either directory names or names of other searchlists. On lookup, all references to searchlists 
are expanded (replaced by their contents) until the expanded searchlist consists only of directory names. An 
entry that is a reference to a searchlist contains the name of the searchlist followed by a colon (Y) (and 
optionally a subdirectory name). This is the same syntax that is used by the file system to denote searchlists. 
It is possible to have both a local and global environment variable with the same name. In this case the local 
variable takes precedent just as in Pascal scope rules. 

Ordinarily, if a local searchlist exists with the same name as a global searchlist, the local searchlist will be 
used. The one exception to this rule is that when a local searchlist contains its own name, that becomes a 
reference to the global searchlist with the same name - not a recursive reference to itself. This behavior is 
useful because it allows the system to specify a default search list for a given subsystem by name and for 
that subsystem to reference its path by that name. However, a user may then define a local searchlist with 
the same name to override the normal search list for that system. The user can then use the global definition 
from within the local definition, allowing the user to add directories to the normal search list for the 
subsystem. 

Note that this applies even if the original searchlist is a global search list For example, Accent searches for 
run files within the "Run:" search list and all other files within the "Default:" search list A user who wants 
to make both searchlists the same can define the global "Run:" search list as "Default:". Then, each time 
the "Run:" search list is resolved, the sytem will actually search the "Default:" search list for the process 
asking for the search. Since the "Default:" search list is first resolved locally, this allows the one (global) 
definition of the "Run:" search list to refer to different "Default:" search lists depending on which process 
resolves it 
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2.2 Definitions 

The following definitions are found in EnvMgrDefs.pas. 

At the shell level, Searchlist environment variable names are distinguished from string environment 
variable names by having a colon (':') as the last character of the name. This colon is NOT used by any of 
the Environment Manager user interface calls and is not returned by ScanEnv Variables. 

{ Env_ Variable: A list of environment entries, each of which is a string. 

const 

Env_Elcment_Size =255; { MaxString } 
type 

Env Element = string[Env_ElementSize]; 

Env_Elcment_ Array = array [0 .. 0] of Env_Element; { hack } 

Env_Variable = t Env_Element_ Array; 

{ A Searchlist name embedded in a searchlist string is followed by 
{ a Searchlist.Separator character. 

const 
Searchlist.Separator = ':'; 



{ Env_Var_Name: The name string for an environment variable. 
{ The syntax of the name is the same as for an arbitrary 
{ entry name in the name server. 

const 

Env_VarName_Size = Entry.Name.Size; 
type 

Env_Var_Name = string[Env_VarName_Size]; 



{ Env.Var.Type: The environment variable type values. 

type 
Env.Var.Type = ( 
Env_String, { Values are lists of strings } 

Env.SearchList); { Value is a search list } 



{ Env.Var.Scope: Flag specifying whether to find environment variable 
{ in the local table, global table, or using the normal method 
{ of local and then global. 

type 
Env.Var.Scope = ( 
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EnvNormal, { Use the normal lookup method } 

EnvJLoeal, { Refer to name in per-process table } 

Env_Global); { Refer to name in global environment 

variable table } 



{ Env_Scan_List: A list of environment variable names, types, and scopes. 

type 
EnvScan.Record = 
record 

VarName : Env_Var_Name; 
VarType : Env_Var_Type; 
VarScope : Env_Var_Scope; 
end; 

En v_Scan_ Array = array [0 .. 0] of Env_Scan_Record; { hack } 
EnvJScan.List = t Env_Scan_ Array; 



{ Error return values for Environment Manager. 



const 
Env.ErrorBase = 1600; 

EnvVariableNotFound = Env_ErrorBase + 1; 
WrongEnvVarType = Env_Error Base + 2; 
BadSearchlistSyntax = EnvErrorBase + 3; 
SearchlistLoop = Env_Error_Base + 4; 
FirstltemNotDefined = Env_Error_Base + 5; 

23 Functions 

The following functions are found in EnvMgrUser.pas. 
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GetEnvVariable 

Returns the value of an environment variable. If the variable is a searchlisU this does not evaluate any 
contained searchlist references. 

Call: 

Function GetEnvVariable( 
ServPort : Port; 
Name : Env .VarName; 
SearchScope: Env_Var_Scope; 
var Variable : Env_Variable; 
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Parameters: 



Results: 



var Variable _Cnt: long; 
varVarTypc : Env_Var_Type; 
var ActualScope: Env_Var_Scope) 
: GeneralReturn 



ServPort-Connection to the Environment Manager for process. 

Name-name of environment variable. 

SearchScope-wheve to search: 

Env_Global global environment only 

Env_Local local environment only 

Env Normal Search the local environment If 

the variable is not there, search the 

global environment. 

Variable-returns a pointer to the variable (a variable-length 
array of strings). 

Variable Cnt-retums the number of entries in variable. 

VarType-vetmns type of environment variable: Env_Searchlist 
or Env_String. 

ActualScope-retams where the variable was actually found 
(Env_Local or EnvGlobal). 

Success 

Environment Variable not found 



SetEnvVariable 

Enters a new environment variable. If the variable is a search list, checks for valid search list syntax and 
ensures that each entry ends in a directory separator ("/") or a searchlist terminator (":"). 

Call: 

Function SetEnvVariable( 

ServPort :Port; 
Name :Env_Var_Name; 
VarType : Env.Var.Type; 
VarScope : Env.Var.Scope; 
Variable : Env_Variable; 
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Parameters: 



Results: 



Variable _Cnt: long) 
GeneralReturn 



ServPort-Cormection to the Environment Manager for process. 

Name-name of environment variable. 

VarType-type of variable to enter: 

Env_String or Env_Searchlist 

VarScope- Where to enter the variable: 

Env,Global global environment 
Env Local local environment 

Variable-pointer to the variable (a variable-length array of 
strings). 

Variable Cnt-number of elements in variable. If the value is an 
empty array, the name is deleted. 

BadName-\f search list name is null or if an entry is malformed. Null 
search list names are ignored. 



ResolveSearchList 

The ResolveSearchList call is used to resolve the value of an environment variable of type EnvSearchList, 
recursively expanding any environment variable references contained therein. If undefined names are 
encountered during the expansion, they are ignored and the expansion is continued It is, however, an error if 
the evaluation results in an empty search list 



can: 



Function ResolveSearchList 
ServPort : Port; 
Name : Env.Var.Name; 
FirstOnly : boolean; 
var Variable : EnvJVariable; 
var Variable _Cnt : long; 
varFirstDefined : boolean) 
: GeneralReturn 



Parameters: 
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ServPort-Port for process environment 

Name-name of search list. 

FirstOnly-if TRUE, only return the first item in the expansion. If 
FALSE, return all items in the expansion. 

^aritf^/e-returns a pointer to the search list (a variable-length 
array of directory names). 

Variable Cni-TQtums the number of entries in search list 

First Defined-TCtums TRUE if the first element in the expansion exists. 
Returns FALSE is it could not be resolved (it was a reference to a 
search list that did not exist). 



Results: 



Success 

SearchListnotfound 
WrongEnvVarType 
SearchListLoop 

ScanEnvVariables 

Lists the defined environment variables by name. 

Call: 

Function ScanEnvVariables( 
ServPort :Port; 
SearchScope: Env_Var.Scope; 
EnvScanList: Env_Scan_List; 
var EnvScanList _Cnt: long) 
: GeneralReturn 

Parameters: 

ServPort-Povt for process environment 

SearchScope-Env Global list global variables only 
Env_Local list local variables only 
Env .Normal list all local variables, and all 
global variables that are not hidden 
by local variables with the same 
names. 
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Results: 



EnvScanList-TQtarns the list of variable names, types, and scopes. 
EnvScanList_C ni-returns the number of entries in EnvScanLisL 

Success 



CopyEnvConnection 

Creates a new connection to the SearchList manager, copying all of the local variables belonging to the old 
connection. 



Call: 



Parameters: 



Function CopyEnvConnection( 
ServPort : Port; 
OldConnection : Port; 
var NewConnection : port) 
: GeneralReturn 



ServPort-Any port to the Environment Manager. 

OldConnection-port designating parent connection. If it is NullPort, 
the new connection will have no local variables; 
otherwise, it will receive copies of all the local 
variables from OldConnection. 

NewConnection-retums port for new connection. 



Results: 



Success 
NoMoreConnections 
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EnvDisconnect 

Destroys a connection to the Environment manager and all associated variables. 

Call: 

Function EnvDisconnect( 

ServPort : Port) 
: GeneralReturn 

Parameters: 
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ServPort-Tpon designating connection. The port is deallocated. 
Success 
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3 The I/O System 

3.1 Introduction 

The 10 (input/output) servers provide processes with the interface to access the 10 devices on a PERQ 
workstation. A standard interface to all the servers presents a common mechanism for acquiring use of the 
device that the given server manages, for making 10 requests to the server for using that device, and finally 
for relinquishing use of that device. For most of the 10 devices the servers permit processes to manipulate 
the device at the lowest level of functionality (i.e., the actual hardware registers). This feature is provided by 
supplying a fairly open-ended definition for the parameters to the main 10 request routine. It is felt that this 
type of control can best provide the flexibility needed by processes to make the device meet the needs of 
their particular applications. This does, however, place greater responsibility upon you to program the 
operation of the device correctly and efficiently. 

The primary role of the server then is to manage the actual details of device interaction (including the 
necessary physical memory requirements), to provide a convenient means for processes to perform 10 
operations, to handle the allocation and deallocation of the device, and to attempt to ensure the integrity of 
the device by restricting certain operations and recovering the device when it appears to be hung. 

Each 10 server registers itself with its local Name Server using a Name/Port pair. The Name part of the 
registration includes the name of the local machine and thus identifies the server (and the corresponding^ 
device) with the machine. Thus a process which desires access to a device on a remote machine can expect 
to receive a port to that remote device server when the local Name Server broadcasts the request for the 
Name over the network. 

3.2 Devices 

The 10 system provides access to all the 10 devices except the disk and network. There is one device server 
for each of the supported 10 devices. The supported 10 devices are: 

1. Floppy GPIB RS232A RS232B (PERQ2 workstation only) Speech 

These devices are currently supported by a Z80 microprocessor in the PERQ which acts as an 10 processor. 

There is a single set of standard interface routines that provides you with access to all of the device servers. 
The way in which you select to which device server your request is being directed is to specify the 
appropriate port associated with that device server as the first parameter of one of the standard interface 
routines. Each device server has a special port registered with the Name Server that provides this unique 
access to the associated device server. The standard interface routines are found in IOUserPas in LibPascal, 
and 10 system definitions for various types used in the parameters for the routines are found in IODefsPas 
in LibPascal. 

33 Basic Routines 
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The user interface to an 10 Server is provided through a small set of standard routines: 
1) Procedure InitIO(RPort; Port ); 



2) Function IO.Version( 

ServPort : ServerNamePort 
): String; 



3) Function OpenIO( 

ServPort : ServerNamePort; 
Var IOPort : ServerlOPort; 
UserPort : UserEventPort 
): GeneralReturn; . 

4) Function CloseIO( 

IOPort : ServerlOPort 
): GeneralReturn; 



5) Function SyncIO( 

IOPort : ServerlOPort; 

Command : IOCommand; 

CmdBlk : Pointer; 

CmdBlk.Cnt : Long; 
Var DataBuf : Pointer; 
Var DataBuf Cnt : Long; 

DataTransferCnt : Long; 

TimeOut : Long; 
Var Status : IOStatusBlk 

): GeneralReturn; 

These routines are discussed in Sections 2.10. 

There are two other routines that will be implemented in a future release of Accent: 

a) Procedure AsyncIO( 

IOPort : ServerlOPort; 
Command : IOCommand; 
CmdBlk : Pointer; 
CmdBlk.Cnt : Long; 
DataBuf : Pointer; 
DataBuf Cnt : Long; 
DataTransferCnt : Long; 
TimeOut : Long 

); 
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b) Function Event( 
EventMsg : Msg; 
Var EvcntType : IOEvent; 
Var DataBuf : Pointer; 
Var DataBuf Cnt : Long; 
Var Status : IOStatusBlk 
): GcncralRetum; 

Except for 1) and b), each of these is actually a remote procedure call to a server and is implemented by 
sending a message to and receiving a reply from the server in order to accomplish the requested operation. 
The message passing interface is provided by modules created by the Matchmaker utility. 

3.4 Modes of Interaction 

Two modes of interaction - Synchronous and Asynchronous - are available for accessing a server to perform 
10 operations. The terms Synchronous and Asynchronous, as used here, do not imply anything about the 
type of data that the device is transferring (e.g., for RS232, it says nothing about whether the data is Bisync 
or Async). Synchronous and Asynchronous here refer to the style of user interaction with the server. 

In the Synchronous mode, the user process makes 10 requests through the SyncIO call. The user process is 
then blocked waiting for the reply message holding the results of the operation. This mode is useful if you 
do not want to deal with the details of the message passing system, since the Matchmaker generated 
interface modules handle the packing, sending, receiving, and unpacking of the messages implementing the 
remote procedure call. The Synchronous mode is also useful when the user process does want to block itself 
until a certain operation has been performed. 

The Asynchronous mode provides a means to queue 10 requests, using the AsyncIO call, without being 
blocked. This permits the user process to continue with other processing while the 10 operation is being 
performed. You are permitted to queue up more than one 10 request with the actual queue size limited by 
the particular server and the available message backlog limit on the server's port. When the server has 
completed a requested operation, it sends the results to you in a message as an asynchronous event which 
you must handle. Obviously, this now requires you to deal with the message system by doing an explicit 
Receive in order to obtain the event Upon receiving an event message, you can then call the Event routine 
which simply unpacks the message and fills in the parameters of the Event call according to the message 
content. (Thus you do not need to know about the details of IPC message formats.) Currently the 
Asynchronous interface is not implemented. 

3.5 Function of Basic Routines 

This section discusses in more detail the standard routines and their parameters. 

Except for the Initio and Event routines, the first parameter to each of the basic routines is a port which is 
created and owned by thepartaiarserse? and* tints* identifies the device server to which the user's request 
is directed. Each server owns two important ports - a ServerNamePort and a ServerlOPort - which provide 
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the access to users. The ScrverNamePort is registered with the Name Server and associated with a unique 
string name identifying the particular server. 

The current existing 10 servers are registered as: 

"[MachincNamelGPIBScrver" 

"[MachincName]FloppyScrver" 

"[MachincName]RS232AServer" 

"[MachincName]RS232BServer" 

"[MachineName]SpeechServer" 

where MachineName is the name of the machine upon which the device resides. This provides the means 
to access the devices on other machines across the network as well as local access. 

User programs acquire send access to a ServerNamcPort through a Lookup call to the NameServer. The 
ServerNamePort can only be used in the call to open the device or within the I0_ Version call. The server 
grants access to the device to the OpenIO caller by returning its ServerlOPort. The ServerlOPort is then 
used as the first parameter in all other calls to the server. Some servers (e.g., the Z80 supported device 
servers) may grant exclusive use of the device and not permit it to be opened again until it has been closed; 
other servers may permit multiple access. 

The Initio call is not directed to the server. The Initio procedure is created by Matchmaker and is part of 
the Matchmaker generated user interface module that implements (using the message system) the remote 
procedure calls. The user calls Initio with the parameter ReplyPort which is a port in the user's space and. 
to which the server is given send access for those remote calls (10_ Version, OpenIO, CloselO, and SyncIO) 
that are implemented with a message send followed by an explicit receive. If the ReplyPort equals NullPort 
in the user call, then Initio will allocate a port in the user's space for the reply messages for remote calls. 
The user must call Initio just once and before the first actual remote call (which should be OpenIO) to a 
server. 

The last parameter in the OpenIO call is the UserEventPorL This is a port owned by the user and to which 
the server will send asynchronous event messages. If the user specifies NullPort for the UserEventPort in his 
call to OpenIO, then the Asynchronous interface will not be enabled. This means that the server will ignore 
calls to AsyncIO and will not pass any other asynchronous events to the user. For now, the user should 
specify NullPort as the UserEventPort since the AsyncIO interface is not implemented. 

The parameters for the actual 10 calls are fairly straightforward. The CmdBlk, for instance, is a generic 
pointer to which the user can recast his own device specific command block pointer. See IODefs.Pas for the 
definition of this device specific command block, IOCmdBlk. CmdBlk_Cnt indicates the number of 
command bytes to which CmdBlk points. The CmdBlk is required to have a long integer occupying its first 
2 words which can be set by the user to provide an ID tag for the 10 command request. This tag is then 
copied into the first 2 words of the Status block when the response to the 10 request is made to the user. 
The ID tag is mostly useful for matching up server responses to 10 requests made through AsyncIO. The 
remainder of the CmdBlk is completely device specific. DataBuf points to a buffer for data transfers and 
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DataBuf_Cnt is the size of the buffer in bytes. The number of data bytes to transfer is indicated by 
DataTransferCnt. 

DataTransferCnt is not a redundant parameter. DataBuf Cnt is only used as an indicator of how many bytes 
pointed to by DataBuf are actually transmitted to/from the server in the message associated with the remote 
procedure call. Thus, for example, in a SyncIO call to read N data bytes, DataBuf should be set to Nil, 
DataBuf Cnt should be 0, and DataTransferCnt should be N when the user invokes the remote procedure. 
Upon return from SyncIO and assuming the server successfully carried out the request, DataBuf will point 
to a buffer holding the N bytes of data. This buffer will have actually been created by the kernel when it 
handles the receipt of the server generated response message to the remote call for SyncIO. The kernel 
maps the data pointed to in the response message into the user's address space and ultimately *the 
Matchmaker generated interface module will set DataBuf to point to that piece of memory. 

TimeOut, when applicable to a given command, indicates how long to wait for the command to complete 
before giving up on it. In most cases, a value of -1 means to not wait, zero means to wait indefinitely, and a 
positive value means to wait that many clock ticks where a tick is approximately 1 microsecond. The Status 
block holds information about the success or failure of the 10 command along with any available device 
status bytes. In the event of failure, the information in the Status block may also show how much of the 
command was performed before failure occurred. The set of IOCommands available will include those like 
IORead, IOWrite, IOReset, IOSense, etc., that are generally applicable to most devices as well as some that 
are device specific. Commands include those for data transfer and control, those for device control and 
configuration, and simple directives to the server. 



3.6 Example of SyncIO for GPIB 

In this section the service provided through the SyncIO call, along with a description of the parameters, is 
presented in the context of a specific example. Full definitions for new types are provided in an IODefs 
module found in Section 4. For GPIB the call and parameters are: 



SyncI0( IOPort 

Command 

CmdBlk 

CmdBlk_Cnt 
Var DataBuf 
Var DataBuf_Cnt 

DataTransferCnt 

TimeOut 
Var Status 
): GeneralReturn; 



IOPort 



Command 



ServerlOPort; 

IOCommand; 

Pointer; 

Long; 

Pointer; 

Long; 

Long; 

Long; 

IOStatusBlk 



As previously mentioned, this is the GPIB server port returned to the user upon 
successfully executing the OpenIO call. 

This is the user requested 10 command. Valid commands for GPIB are: 



IOSense 
IODevRead 



IORead 
IOReset 
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CmdBlk 

CmdBlkCnt 
DataBuf 

DataBufCnt 

DataTransferCnt 

TimeOut 



Status 



IOWrite 

IOWriteEOI 

IOFlushlnput 

IOReadHiVol 

IOWriteHiVol 



IODevWrite 
IOWriteRegisters 
IOSetBufferSize 
IOFlushOutput 



Each command will be discussed after presenting the rest of the parameters. 

This points to a record holding the CmdIDTag as well as device specific 
command bytes that are required for the command. The user's pointer to his 
IOCmdBlk for GPIB should be recast to a generic pointer. The definition for 
CmdBlk is given in Section 4. 

The number of valid bytes in the CmdBlk. This is always at least 4 to account for 
the CmdIDTag. 

This points to a buffer for the data which is to be sent or received. It is only used 
with the IORead, IOWrite, IOReadHiVol, IOWriteHiVol, and IODevWrite 
commands. 

The number of data bytes held in the buffer pointed to by DataBuf. 

Thenumber of bytes to read/ write to/from the data buffer. 

The maximum number of clock ticks to wait before giving up on the command. 
A TimeOut value that is zero means to wait indefinitely. A TimeOut value of -1 
means to not wait at all for some commands (e.g. IORead to get data from the 
ring buffer) and means to wait indefinitely for other commands (i.e., where to 
not wait would make no sense). A positive TimeOut value means to wait that 
many clock ticks for the 10 operation to complete. A clock tick is approximately 
1 microsecond. For some commands, the TimeOut is irrelevant and is ignored. 
In some cases, when a command times out, the server will issue a device reset 
automatically. This is done for those commands for which a message is sent to 
the Z80. Since the Z80 always gives an ACK/NAK for each command message, 
a time out would indicate that the device is hung. The only command that can 
free the device for subsequent commands is device reset 

This shows the success or failure of the Command and, in either case, indicates 
how much of the command was performed. Also included is device status from 
the most recently issued IOSense command since the last device reset was issued. 
Obviously, the device status could be empty. Status will be defined by 
IOStatusBlk, IOSenseStatusBlk, and GPIBSenscStatus (see the definitions in 
Section 4). In the IOStatusBlk, HardStatus is status information provided by the 
device for the given Command. For IORead, for example, it is the error byte 
that is supplied with each character in the input ring buffer. SoftStatus is 
supplied by the server and provides a logical indication of the Command 
completion status. A list of the values used for SoftStatus is exported by the 
IODeft module. IOSuccess is the value returned in SoftStatus when the 
Command is successful. When command bytes are present, 

CmdBytesTransferrcd indicates how many of the bytes were actually transferred. 
DataBytesTransferred serves a similar function when the Command involves 
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data transfer. DcviceStatus for GPIB indicates the last available status from the 
internal registers of the TMS 9914 GPIB Controller chip which provides the 
interface to the GPIB. Refer to the Texas Instruments "TMS59914 GPIB 
Controller Data Manual" for a detailed description of this chip. 

3.7 Commands for GPIB 

In a number of the commands, the Z80 will wait until the data in the Z80's GPIB output ring buffer has 
been transmitted over the GPIB bus before actually initiating the command. Since some commands seize 
control and/or reconfigure the bus, it is necessary for the Z80 to wait until its GPIB output buffer has been 
drained before initiating those commands. This ensures the integrity of previous IOWrite commands which 
have sent output data for GPIB. 

The standard TimeOut mechanism used for most commands is: 

TimeOut < = means wait indefinitely 

TimeOut > means wait TimeOut clock ticks 
and commands that do time out are followed immediately by a server issued device reset. 
SoftStatus is returned for each command and indicates success or the reason for failure. A list of SoftStatus 
codes with their meanings can be found in the IODefs module. A Command whose parameters are in error 
will be rejected and SoftStatus will indicate why. These types of errors will not be listed in the discussions' 
below. Assuming no parameter errors, the standard values for SoftStatus for most GPIB commands will be: 

IOSuccess Command completed successfully. 

IOTimeOut Command did not complete within the TimeOut period. 

IOUndefinedError Command was NAKed by the Z80. 

1. IOSense provides 10 bytes of status information from the Z80. Upon return, DeviceStatus in 
Status holds the count and the status bytes. The first 6 status bytes represent the register values in 
the TMS 9914 GPIB Controller chip at the time of the last Z80 GPIB interrupt and the remaining 
4 bytes show values current with the issued IOSense. (These are shown in the GPIBSenseStatus 
record in Section 4.) Note that current values for IntStatO and IntStatl cannot be obtained since 
reading those registers dismisses the interrupts that the bit maps in those registers represent. (See 
TMS 9914 Data Book for more details.) The server also maintains a copy of these 10 status bytes 
and copies them into the DeviceStatus field of Status for subsequent IOCommands. The server 
will always zero its copy of DeviceStatus after a device reset TimeOut for IOSense is standard. 
SoftStatus will be lOSucess, IOTimeOut, or IOUndefinedError. 

2. IOReset puts the GPIB Controller into the idle state by issuing a device reset for GPIB to the 
Z80. This clears the Z80's GPIB input and output buffers (any data is discarded) and puts the 
TMS 9914 into the idle state by performing a Software Reset aux command. The TMS 9914 
interrupt mode is reset for Data In and Data Out interrupts only, the Hdfa/Hdfe aux commands 
are disabled (in case they were previously set), and any data holdoff is released using Rhdf aux 
command. The PERQ workstation's GPIB input ring buffer is not affected. This command is also 
issued implicitly by the server for some of the other commands when they time out. TimeOut for 
IOReset is ignored since the device reset should never fail. 
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3. IOWritcRcgistcrs is used to program the TMS 9914 registers. CmdBlk points to the user's 
IOCmdBlk which, for IOWritcRegisters, contains an array of GPIBWritcRegister elements. Each 
GPIBWriteRegister is a pair of bytes where the first byte indicates the TMS 9914 register and the 
second byte is the value to be written. CmdBlk_Cnt indicates the total number of bytes and, thus, 
must be even. TimeOut and SoftStatus are standard. CmdBytesTransfcrred shows the total 
number of bytes transferered. 

4. IOFlushlnput is used to suspend GPIB bus activity and extract all remaining GPIB input data 
held in the Z80. This is done by issuing a Tea aux command to the GPIB Controller chip to 
suspend bus activity and sending all data accumulated in the Z80 GPIB input ring buffer to the 
PERQ workstation. In addition, any byte that is being held in the controller chip's Data In 
register is removed and also sent to the PERQ workstation. All data returned is deposited in the 
workstation's GPIB input ring buffer and can be obtained by the user with the IORead 
command. Note that the Tea aux command is not issued by the Z80 until the Z80's GPIB output 
buffer has been drained. TimeOut and SoftStatus are standard. 

5. IOFlushOutput flushes the Z80's GPIB output data ring buffer by waiting until all the data has 
been drained from the buffer. TimeOut and SoftStatus are standard. 

6. IORead is used to extract data from the PERQ workstation's GPIB input ring buffer. This does 
not require any interaction with the Z80 and, thus, a time out does not result in a device reset. 
When the user makes the remote call, DataBuf should be Nil, DataBuf_Cnt 0, and 
DataTransferCnt should indicate the number of bytes to read. Upon return from the call, 
DataBuf will have been set to point to the buffer holding the data sent by the server (and may be 
Nil). Each character in the PERQ workstation input ring buffer has a status byte (the value of 
IntStatO at the time of the Data In interrupt) associated with it. The server extracts characters and 
puts them into the DataBuf until either the DataTransferCnt is satisfied, a character's status byte 
shows an error, or no characters remain and the TimeOut expires. DataBytesTransferred is set to 
the number of characters returned in the DataBuf. SoftStatus is IOSuccess if the command 
succeeds completely. IONoDataFound is returned if no characters were found and the TimeOut 
expires. IOTimeOut is returned if the requested DataTransferCnt was not satisfied and the 
TimeOut expired. If the server finds a character with its status byte showing an error, it 
terminates further reading, puts the character into the DataBuf, sets HardStatus with the 
character's status byte, and sets SoftStatus to the appropriate error (IOCircBufOverflow or 
IOEndOflnput). For TimeOut, a value of means wait indefinitely, -1 means don't wait, and > 
means the obvious. 

7. IOWrite sends data to the Z80 to be transmitted by the GPIB controller chip using Data Out 
interrupts. The Z80 buffers the data and sends an ACK when it has room in its buffer for another 
packet (i.e., 12 bytes is the most that can be sent in a single data packet) of data from the PERQ 
workstation. The server handles the user's IOWrite command by packaging the user's data 
pointed to by DataBuf into 12-byte packets and sending them to the Z80 as indicated above. 
(Obviously, IOWrite will be optimal when the DataBuf Cnt is a multiple of 12.) Thus the actual 
transmission of the last of the data bytes onto the GPIB bus can only be verified by the user 
following up with an IOFlushOutput command or some other command that waits until the Z80 
GPIB output buffer has been drained. TimeOut and SoftStatus are standard. 
DataBytesTransferred will indicate how many bytes were actually sent to the Z80 for 
transmission. 
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8. IOWritcEOI is the same as IOWrite except that the last data byte will be sent with the GPIB bus 
EOI line set The user must take care not to send more output data until the Z80 GPIB output 
buffer drains-otherwise, EOI may be set on the wrong byte. Draining of the buffer can be verified 
explicitly with IOFlushOutput or implicitly with one of the other commands. 

9. IOSetBufferSize is used to set the size of the physical buffer that is used for the IOReadHiVol 
and IOWriteHiVol commands. The default size is set to 1024 bytes when the device is allocated 
by the server in the OpenIO call. CmdBlk_Cnt should be 8 for this command. 

10. IOReadHiVol reads data from the GPIB using a DMA channel and thus provides a high transfer 
rate. As with IORead, DataBuf is Nil and DataBuf Cnt is when the user makes the remote call 
and are set appropriately upon return. DataTransferCnt must be greater than 1 (since the Z80 
DMA cannot handle a byte count of 1). TimeOut and SoftStatus are standard. 
DataBytesTransferred indicates the number of bytes actually read. IOReadHiVol may be 
programmed to terminate early if EOI is raised by the sending device. When this feature is 
enabled and occurs, a completion of IOEndoflnput is returned for SoftStatus and 
DataBytesTransferred must be checked to determine the amount of data actually received. 

11. IOWriteHiVol writes data to the GPIB using a DMA channel. DataBuf points to a buffer holding 
DataBuf Cnt bytes. DataTransferCnt has the same restriction as for IOReadHiVol. TimeOut and 
SoftStatus are standard. DataBytesTransferred indicates the number of bytes actually written to 
GPIB and only needs to be checked when SoftStatus is not IOSuccess. The Z80 will wait for the 
Z80 GPIB output data ring buffer to drain before starting the HiVol operation. 

12. IODevRead and IODevWrite are somewhat complex commands that, in their simplest form, can 
be used just to configure the GPIB bus to change the Talker/Listener device on the bus. The 
CmdBlk points to a record containing the CmdIDTag followed by a GPIBDevCmdBlk. See 
Section 4 for the definition of GPIBDevCmdBlk. 

By setting all fields in GPIBDevCmdBlk to or false except the PrimAddr and SecAddr, IODevRead 
would simply configure the bus with the device in PrimAddr and SecAddr as the new Talker; IODevWrite 
would configure a new Listener. If the SecAddr is not used, it should be set to 255. These commands are 
useful since they reduce a commonly used sequence of IOWriteRegister and IOWrite commands to a single 
command. They can also be used to configure the bus and set up the GPIB controller chip's interrupt mask 
registers appropriately for HiVol Read/Write commands. The basic algorithms for DevRead and Dev Write 
are given at the end of this section. 

For IODevRead, CmdBlkCnt should be 10. If ReadCount in GPIBDevCmdBlk is non-zero, the Z80 will 
wait until ReadCount bytes have been read (using Data In interrupts) from the configured GPIB Talker 
device and the Z80 will then hold off further input using the Hdfa aux command. As the data accumulates 
in the Z80, it is sent up to the PERQ workstation's GPIB input ring buffer. The Z80 returns (and thus the 
IODevRead completes) only after the requested number of bytes have been read and sent to the PERQ 
workstation. To obtain the data, the user must subsequently use the IORead command (i.e., for 
IODevRead, DataBuf is NIL and DataBuf Cnt is 0). 

For IODevWrite CmdBlk_Cnt should be 9. DataBuf points to DataBuf Cnt bytes of data to be transmitted 
on GPIB using Data Out interrupts. As with the IOWrite command, the data is shipped to the Z80 in 
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packets. (In terms of efficiency, note that the first packet holds the 5 byte GPIBDevCmdBlk plus only 7 data 
bytes.) 

For both IODevRead and IODevWrite, TimeOut and SoftStatus are standard. CmdBytesTransferred 
should be the same as CmdBlk_Cnt. DataBytesTransferrcd is valid only for IODevWrite and indicates the 
number of data bytes actually sent to the Z80 for transmission. 

The Z80 will wait before initiating the DevRead and DevWrite commands until the Z80 GPIB output ring 
buffer has drained. The basic algorithm for each command is then given below using the following 
definitions: 

AuxReg -- 9914 Auxiliary Command Register 

DataOut - 9914 Data Out Register 

Dataln - 9914 Data In Register 

MaskO - 9914 Interrupt Mask Register 

Maskl - 9914 Interrupt Mask Register 1 

DevWrite : 

With GPIBDevCmdBlk, GPIBDevCmdBlk. Options do 

begin 

AuxReg := Tea; 
AuxReg := Ton, off; 
AuxReg := Lon, off; 

If SetlntOMask then MaskO := IntOMask; 
If SetlntlMask then Maskl := IntlMask; 
If not OmitBusConf ig then 
begin 

DataOut := Unt; 

If not OmitUnlisten then DataOut := Unl; 
If (0 <= PrimAddr) and (PrimAddr <= 30) then 
begin 

DataOut := Mia + PrimAddr; 
If (0 <= SecAddr) and (SecAddr <= 31) then 
DataOut := Msa + SecAddr; 
end; 
{ Note: We load the DataOut with the first } 
{ interface command (Unt) and the rest } 
{ are sent using Bus Out interrupts. } 
end; 

AuxReg := Ton, oh; 

If not OmitGoToStandby then AuxReg : s Gts; 
{Now handle the data bytes } 
If DataTransferCnt does not equal then 
begin 

DataOut := first data byte; 

{ Remaining data bytes are transmitted using } 

{ Bus Out interrupts } 

If ForceEOI then last data byte is sent with EOI; 

If WaitOnData then 
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wait till all data sent before returning 
else 

return without waiting; 
end; 
end { with }; 

DevRead : 

With GPIBDevCmdBlk, GPIBDevCmdBlk. Options do 
begin 

AuxReg := Tea; 
AuxReg := Ton, off; 
AuxReg := Lon, off; 

If not OmitBusConf ig then clear Dataln; 
If SetlntOMask then MaskO = IntOMask; 
If SetlntlMask then Maskl := IntlMask; 
If not OmitBusConf ig then 
begin 

DataOut := Unt; 

If not OmitUnlisten then DataOut := Unl; 
If (0 <= PrimAddr) and (PrimAddr <= 30) then 
begin 

DataOut :- Mta + PrimAddr; 
If (0 <= SecAddr) and (SecAddr <= 31) then 
DataOut := Msa + SecAddr; 
end; 
{ Note: We load the DataOut with the first interface } 
{ command (Unt) and the rest are sent using } 
{ Bus Out interrupts. } 

end; 

if HoldOffOnEOI then 

AuxReg := Hdfe, on 
else 

AuxReg := Hdfe, off; 
AuxReg := Hdfa, off; 

AuxReg := Rhdf; {Release any previous holdoff } 

AuxReg := Lon, on; 
AuxReg := Gts; 
If ReadCount <> then « 
begin 

Wait until we have input ReadCount data bytes using 
Bus In interrupts and issue 

AuxReg :- Hdfa, on before the last byte is input, 
end 
end { with }; 

3.8 Commands for RS232, Speech and Floppy 

The valid SyncIO commands for the other servers will be discussed here. The description of the parameters 
to SyncIO is essentially the same as that given for GPIB in Section 2.4. Also, the description of th 
commands for GPIB in Section 2.5 is applicable except for the differences noted below for each device. The 
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timeout mechanism, use of the status block, and the delay waiting for the device's output ring buffer to 
drain before initiating certain commands is similar to the case for GPIB. 

3.8.1 RS232A 

The valid commands for RS232A are: 



IOSense 

IOReset 

IOFlushlnput 

IOFlushOutput 

IOSetBaud 

IOWritcRcgisters 

IOSense 



IOReset 



IOFlushlnput 



IOSetBaud 



IORead 



IOReadHiVol 
IOWriteRegisters 



IORead 

IOWrite 

IOSetBufferSize 

IOReadHiVol 

IOWriteHiVol 

Only 2 bytes of status information are held in the DeviceStatus record. These 
correspond to the last available values obtained for the ReadRegisters and 1 of 
the Serial 10 (SIO) chip which implements the RS232 interface. 

This configures the RS232A channel to handle 9600 baud, 8-bit asynchronous 
data using 1 1/2 stop bits and no parity. The Data Terminal Ready (DTR) and 
Request To Send (RTS) signals (RS232 pins 20 and 4) are turned on and the SIO 
chip is programmed with Auto Enables mode. Auto Enables means that the 
Clear To Send (CTS) and Data Carrier Detect (DCD) inputs (RS232 pins 5 and 
8) are used as the enable signals for the respective transmission and reception of 
RS232 data bytes. This means that CTS must be on before the SIO chip will 
transmit a byte. And the DCD signal must be on before the SIO chip will 
actually assemble data bytes from the incoming bit stream. 

This simply sends all accumulated data held in the Z80 RS232A input ring 
buffer to the PERQ where it is deposited in the PERQ's RS232A input ring 
buffer. 

This is used to modify the rate of the internal baud rate clock used for 
transmitting and receiving asynchronous RS232 data bytes in their bit-serial 
form. The baud rate codes to use are defined in IODefs.Pas and include a code 
(RSExt) for synchronous RS232 data where external clocks are used to 
synchronize the character bit stream. CmdBlk_Cnt should be 6 for IOSetBaud. 

Similar to the GPIB example except that the per character status byte is the 
status byte provided by the SIO chip that accompanies each input data byte 
assembled by the chip. This byte is the value of SIO ReadRegister 1 which 
shows such errors as parity, framing, and overrun for the given input data byte as 
well as the end of frame condition and residue codes for SDLC data. Thus the 
SoftStatus code returned for IORead will be one of IOSuccess, IOTimeOut, 
IONoDataFound, IOCircBufOverFlow, IOParityError, IOFramingError, or 
IOEndOfFrame. 

Similar to GPIB. Note, however, that this command is not very useful for RS232 
and that the EOI feature of GPIB is not present. 

Permits you to program all SIO except WriteRegisters 1 and 2. These 2 registers 
are used to control the interrupt modes of the SIO chip. Registers 6 and 7 are 
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used to specify the sync characters used for synchronous RS232 data transfers. 
Bit definitions for the other 4 registers arc given in Figures 1 through 4. 



WRITE REGISTER 9 



07 D6 OS 04 03 02 | Dl 08 



9 


9 


9 


Register 9 


9 


9 


1 


Register 1 


9 


1 


a 


Register 2 


9 


1 


i 


Register 3 


1 


a 


9 


Register 4 


1 


9 


1 


Register 5 


1 


i 


9 


Register S 


1 


i 


1 


Register 7 



9 





8 


9 


9 


1 


8 


1 


9 


9 


1 


1 


1 


8 


8 


1 


9 


1 


1 


1 


8 


1 


1 


1 



Null Code 

Send Abort (SDLC) 

Reset Ext/Status Interrupts 

Channel Reset 

Enable Int On Next Rx Character 

Reset Txlnt Pending 

Error Reset 

Return from Int (CH-A only) 



9 


9 


Null Code 


9 


1 


Reset Rx CRC Checker 


1 


9 


Reset Tx CRC Generator 


1 


1 


Reset Tx Underrun/EOM Latch 



Figure 1. Write Register Bit Functions 
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WRITE REGISTER 3 



D7 06 OS Of 03 OZ 01 08 



8 8 Rx 5 Bits/Character 

8 1 Rx 7 Bits/Character 

1 8 Rx 6 Bits/Character 

1 1 Rx 8 Bits/Character 



Rx Enable 



Sync Character Load Inhibit 



Address Search Mode (SOLO 



Rx CRC Enable 



Enter Hunt Phase 



Auto Enables 



Figure 2. Write Register 3 Bit Functions 
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WRITE REGISTER 4 



D7 | PS | 05 | 04 | 03 | 02 1 01 | D8 \ 



Parity Enable 

Parity Even(l). Odd(0) 



Sync Modes Enable 

1 1 Stop Bit/Character 

1-1/2 Stop Bits/Character 

1 2 Stop Bits/Character 



9 8 Bit Sync Character 

1 1G Bit Sync Character 

SDLC Hode (01111110 Flag) 

1 External Sync Mode 



XI Clock Mode 

1 X1G Clock Mode 

1 X32 Clock Mode 
1 1 X64 Clock Mode 



Figure 3. Write Register 4 Bit Functions 
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URITE REGISTER S 

f D7 I 06 | D5 1 D* | Dp I 02 I ^ A^fl 



Rx CRC Enable 



RTS 



CRC1S (U. SDLC (9) 



Tx Enable 



Send Break 



DTR 



Tx 5 Bits (or Less) /Character 
Tx ? Bits/Character 
Tx 6 Bits/Character 
Tx 8 Bits/Character 



Figure 4. Write Register 5 Bit Functions 
■me byte masks.used, for example, to program the chip for the default settings 
obtained by IOReset are: 
Register # Bvte Mask (in octal) 
030 

ioo 

4 110 
3 341 

5 352 

3 8 2 RS232B 

' ' . . f p«wr k the same as RS232A except that the IOSetBufferSize, IOReadHiVol, and 

The description of RS232B is the same as k^za p ^ pERQ i workstations. 

IOWriteHiVol commands are not present. Note again that RS232B does not exist r 

3.8.3 Speech 

The valid commands for speech are: 

IOSense IOWrite 

IOReset IOSetBufferSize 

IOSctBaud IOWriteHiVol 
IOFlushOutput 
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The description of these is the same as for RS232A except as noted below. The speech data output is 
implemented using the same type of SIO chip as for RS232 but configured instead for synchronous 8-bit 
data transmission using a single sync character of 252 (octal) which is automatically transmitted at the start 
of data transfers. The default baud rate is set at 32 KHz. 

IOReset Configures the hardware for the default state described above and clears the 

speech output ring buffer. 

IOSetBaud Changes the baud rate for bit-serial transmission of speech data to the actual 

speech output hardware in the PERQ. The SpeechTxRate field in the CmdBlk is 
set to obtain the desired bit rate in the following manner: 

PERQ1: 



3.9 Floppy 



SpeechTxRate = 2.456 * 10t6 



16 * (Desired Baud Rate) 



PERQ2 

SpeechTxRate = 4 * 10t6 



Desired Baud Rate 



A SpeechTxRate of 5 for PERQ1 and 125 for PERQ2 will 
give a baud rate of approximately 32 KHz. Note also 
that PERQs that have a portrait/landscape electro- 
magnetic ranging tablet instead of a Summagraphics 
BitPad tablet have a further restriction. Since the 
electromagnetic ranging tablet shares the same baud 
rate clock with Speech, modifying the Speech baud 
rate may have unpredictable effects on the behavior 
of the tablet. You may have to unplug the tablet 
while your application runs, and you should restore 
the baud rate to 32KHz before your program terminates. 
This can easily be done by issuing the IOReset command. 



The valid commands for floppy are given in the table below, along with some other information that will be 
explained below. 
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Table 1. Valid Commands for Floppy 









Returns 


Returns 


10 Command 


CmdBlk Cnt 


Device Status 


Hard Status 


IOReset 


4 




failure 


on failure 


IOSense 


4 




on success 


no 


IOSenseDrive 


4 




on success 


no 


IOReadlD 


6 




on success 


no 


IOSetDensity 


5 




no 


no 


IORecalibrate 


4 




on failure 


on failure 


IOSeek 


7 




on failure 


on failure 


IOFormat 


8 




on failure 


on failure 




IORead 


8 


on 


failure 


on 


failure 








IOWrite 


8 


on 


failure 


on 


failure 







The parameters to SyncIO have a similar description as that for GPIB in Section 2.4 The main difference is 
in the Status parameter. For Floppy, the DeviceStatus record in the IOStatusBlk is only valid as indicated in 
the table above. From the table "on failure" that the command failed for reasons other than IOTimeOut, 
IOUndefinedError, or some parameter error. This means that the floppy controller hardware initiated the 
command but failed to complete it. The controller always provides status information at the termination of 
each command. These bytes are returned to you "on failure" as the DeviceStatus record which for floppy is 
a FloppyResultStatus record as defined in IODefs.Pas. Also, "on failure", HardStatus in Status will be 
assigned the first byte of the device status which is Status Register from the controller and is represented 
in the FloppyResultStatus record as: 

Unit : Bit2 {always 0} 
Head : Bitl 
NotReady : Boolean 
EquipFault : Boolean 
SeekEnd : Boolean 
IntrCode : ( 00 - Normal 

01 - Abnormal 

10 - InvalidCmd 

11 - DriveRdyChange) 

DeviceStatus is also returned "on success" for those commands listed in the table whose function it is to 
explicitly extract status about the last floppy operation or current drive state. Also shown in the table is the 
CmdBlk_Cnt required for each of the floppy commands. From the definition of IOCmdBlk in IODefsPas, 
we see that the command bytes for the commands involving actual floppy IO include a device address 
specifying the Unit, Head, Cylinder, and Sector. The range of these parameters is: 

Unit - always 

Head -0...1 

Cylinder - ... 76 

Sector - 1 ... 26 
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For read/write commands, the logical mapping of floppy sectors is done by first increasing the sector 
number, then the cylinder number, and lastly the head number. For IORcad and IOWritc, the starting 
address on the floppy is given in the CmdBlk and DataTransferCnt indicates how many bytes should be 
read/written. To satisfy the requested number of bytes, the server will continue to read/write consecutively 
numbered sectors and will continue, if necessary, by advancing to the next cylinder on the same side. When 
the last cylinder on side is read/written, it switches to side 1 at cylinder and sector 1 and continues until 
the byte count is satisfied. Thus the server will implicitly do seek operations in order to satisfy the 
DataTransferCnt If the DataTransferCnt given is greater than the number of bytes that could possibly be 
read/written from/to the floppy from the starting address to the end of the floppy, then the server will not 
attempt to start the command and will reject it with an error code of IONotEnoughData / 
IONotEnoughRoom. 

The other floppy commands are fairly straightforward. The IOFormat command is used to format all 26 
sectors of a single track designated by the address in the CmdBlk. You must also specify in the CmdBlk the 
default data pattern to be written into the formatted sectors of that track. DataBuf for IOFormat must point 
to a buffer holding 26 4-byte SectorlDs for each of the 26 consecutive sectors on the track. Each 4-byte 
SectorlD is given as: 

Byte Information Range 

1 Cylinder 0...76 

2 Head 0...1 

3 Sector 1...26 

4 SectorSizeCode 0...1 

where a SectorSizeCode of is used for single density with 128 bytes per sector and 1 is used for double 
density with 256 bytes per sector. The server does not check the 104 (26 x 4) byte buffer of SectorlDs for 
correctness. You can also perform hardware interleaving of floppy sectors by simply specifying the desired 
sector number in each SectorlD. Thus if the list of sector numbers specified in the 26 consecutive SectorlDs 
is given by 1, 14, 2, 15, 3, 16, . . ., 12, 25, 13, 26, then a hardware interleave factor of 2 is achieved on that 
track. The IORecalibrate command forces the floppy to seek to head and cylinder 0. IOReset does a 
device reset followed by a recalibrate. The timeout mechanism for floppy is the same as that described for 
GPIB in Section 2.5. 

3.10 Definitions 

The following definintions can be found in the Module IODeft. 
const 

{ Define return values for 10 errors. 

IOBaseMsglD = 4000; 

IOSuccess = SURESS; 
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IOErr = IOBascMsglD; 

IOUndcfinedError = IOErr + 1; 
IOTimcOut = IOErr + 2; 

IODeviceNotFree = IOErr + 3; 
IOInvalidlOPort = IOErr + 4; 
IOBadUscrEventPort = IOErr + 5; 
IOBadPortRefercnce = IOErr + 6; 
IOIllegalCommand = IOErr + 7; 
IOBadCmdBlkCount = IOErr + 8; 
IOBadDataByteCount = IOErr + 9; 
IOBadRegistcrNumbcr = IOErr + 10; 
IONotEnoughRoom = IOErr + 11; 
IOBadBaudRate = IOErr + 12; 

IONoDataFound = IOErr + 13; 

IOOverRun = IOErr + 14; 

IOParityError = IOErr + 15; 

IOFramingError = IOErr + 16; 

IOCircBufOverFlow = IOErr + 17; 
IOEndOfFrame = IOErr + 18; 

IOEndOflnput = IOErr + 19; 

IOBadSectorNumber = IOErr + 20; 
IOBadCylinderNumber = IOErr + 21; 
IOBadHeadNumber = IOErr + 22; 
IOUndcterminedEquipFault = IOErr + 23; 
IODeviceNotReady = IOErr + 24; 
IOMissingDataAddrMark = IOErr + 25; 
IOMissingHeaderAddrMark = IOErr + 26; 
IODeviceNotWritable = IOErr + 27; 
IOSectorNotFound = IOErr + 28; 
IODataCRCError = IOErr + 29; 

IOHcaderCRCError = IOErr + 30; 
IOBadTrack = IOErr + 31; 

IOCylinderMisMatch = IOErr + 32; 
IODriveReadyChanged = IOErr + 33; 
IONotEnoughData = IOErr + 34; 
IOBadBufferSize = IOErr + 35; 

type 
ServerNamePort = Port; 
ServerlOPort = Port; 
UserEventPort = Port; 

IOCommand = (IOSense, IOReset, IOWriteRegisters, 
IOFlushlnput, IOFlushOutPut, IORead, 
IOWrite, IOWritcEOI, IOReadHiVol, 
IOWriteHiVol, IODevRead, IODevWrite, 
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IOSetBaud, IOSctStream, IOSetAttention, 
IOAbort, IOSuspend, IOResume, 
IOSeek, IORecalibrate, IOFormat, 

IOReadlD, IOSenseDrive, IOSetDensity, 
IOSetBufferSize, IONullCmd); 

IOEvent = (IOReply, AsyncData, Attention, Distress, Acknowledge); 

pIOMessage = tlOMessage; 
IOMessage = record 

Head : Msg; 

Body : array[0..1023] of integer; 

{ Note: The size of the Body is dependent 

{ upon the maximum size of messages 

{ that are passed between the Client 

{ and Server, This size is determined 

{ by the number and type of the parameters 

{ in the remote calls, the IPC conventions 

{ for packing data in-line, and the added 

{ parameters in the message that MatchMaker 

f inserts for coded return values. 

{ The actual size needed for 10 messages 

{ is 46 given current IPC conventions, 

{ MatchMaker requirements, and actual 

{ parameters for the remote calls. Future 

{ changes to any of the above may require 

{ modifying the size for the Body. Accent 

{ gurus say that 1024 is a reasonably safe 

{ maximum for the time being and that we 

{ should just use that here. 

end; 

GPIBWriteRegister = packed record 

case RegNum: Bit8 { really 0..6 } of 
0: ( { To be defi ned later! } ); 
1: (RegVal : BitS) 
end; 

SIOWriteRegister = packed record 

case RegNum: BitS { really 0..7 } of 
0: ( { To be defi ned later! } ); 
1: (RegVal : Bit8) 
end; 

GPIBDevCmdHead = packed record 
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Options: packed record { Bitmap to select cmd actions } 
SetlntOMask : boolean; 
SetlntlMask : boolean; 
OmitBusConfi g : boolean; 
OmitUnListen : boolean; 
case boolean of 

true : ( { f or IODevRead cmd } 
HoldOff OnEOI : boolean; 
unused2 : Bit3 

); 

false: ( { for IODev Write cmd } 
OmitGoToStandby : boolean; 
WaitOnData : boolean; 
ForceEOI : boolean; 
unusedl : Bitl 

); 

end; 
IntOMask : Bit8; { Mask for 9914 Interrupt Reg } 
IntlMask : Bit8; { Mask for 9914 Interrupt Reg 1 } 
PrimAddr : Bit8; { Primary Address of device } 
SecAddr : Bit8; { Secondary Address of device } 
case boolean of 
true: ({ for IODevRead } 

ReadCount : Bit8 

); 

false: ( { for IODevWrite } 
{ nothing } 

); 

end; 
DensityType = (SingleDensity, DoubleDensity); 

pIOCmdBlk = tlOCmdBlk; 
IOCmdBlk = packed record 
CmdIDTag: long; 
case integer {IODevice} of 
0: {No Device for generic access} 
(case integer of 
0: {Byte access} 
(CmdByte: packed array[0..0] of Bit8); 

1: {Word access} 
(CmdWord: packed array[0..0] of integer); 

2: {Register access} 
(WriteReg: packed array [stretch(0)..stretch(0)] of 
packed record 
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): 



RegNum: Bit8; 
RegVal: Bit8 
end) 



1: {GPIB} 
(case IOCommand of 
IOSetAttention: { AsyncIO only } 
(GPIBEnableATN: boolean); 

IOSetStream: { AsyncIO only } 
(GPIBEnableStream: boolean; 
GPIBBlockingFactor: integer); 

IOSetBufFerSize: 
(GPIBBufFerSize: long); 

IOWriteRegisters: 
(GPIBWriteReg: packed array[stretch(0)..stretch(0)] 
of GPIBWriteRegister); 

IODevRead, IODevWrite: 
(GPIBDevCmdBlk: GPIBDevCmdHead) 

); 

2: {RS232A, RS232B} 
(case IOCommand of 
IOSetAttention: { AsyncIO only } 
(RS232EnableATN: boolean); 

IOSetStream: { AsyncIO only } 
(RS232EnableStream: boolean; 
RS232BlockingFactor: integer); 

IOSetBufFerSize: { RS232A only } 
(RS232Buff erSize: long); 

IOSetBaud: 
(RS232TxBaud: Bit8; 
RS232RxBaud: Bit8); 

IOWriteRegisters: 
(RS232WriteReg: packed array[stretch(0)..stretch(0)] 
of SIOWriteRegister) 

): 
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3: {Speech} 
(case IOCommand of 
IOSctAttention: { AsyncIO only } 
(SpeechEnableATN: boolean); 

IOSetBufferSize: { SpeechA only } 
(SpeechBuff erSize: long); 

IOSetBaud: 
(SpeechTxRate: integer); 

IOWriteRegisters: 
(Speech WriteReg: packed array[stretch(0)..strctch(0)] 
of SIOWriteRegister) 

); 

4: {Floppy} 
(case IOCommand of 
IOSetAttention: { AsyncIO only } 
(FloppyEnableATN: boolean); 

IOSetDensity: 
(FloppyDensity: DensityType); 

IORead, IOWrite, IOFormat, IOSeek, IORecalibrate, 
IOReadlD, IOSenseDrive: 
(FloppyUnit : Bit8; 
FloppyHead : BitS; 
case IOCommand of 
IORead, IOWrite, IOFormat, IOSeek: 
(FloppyCylinder: Bit8; 
case IOCommand of 
IORead, IOWrite: 

(FloppySector: Bit8); 
IOFormat: 
(FloppyFmtData: Bit8) 



) 

end; 



) 



) 



GPIBSenseStatus = packed record { IOSense to GPIB provides } 
{ first 6 bytes arc status at time of last interrupt } 
IntStatO : Bit8; { Interrupt Status } 
IntStatl : Bit8; { Interrupt Status 1 } 
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IntAddrStat : Bit8; { Address Status } 
IntBusStat : Bit8; { Bus Status} 
IntAddrSwch : Bit8; { Address Switch } 
IntCmdPass : Bit8; { Command Pass Through } 

{ next 4 bytes arc current status } 
CurAddrStat : Bit8; { Address Status (now) } 
CurBusStat : Bit8; { Bus Status (now) } 
CurAddrSwch : Bit8; { Address switch (now) } 
CurCmdPass : Bit8; { CurCmdPass (now) } 
end; 

SlOSenseStatus = packed record 

{ Read General Status - SIO Chip's Read Register #0 } 

RxCharAvailable : boolean; 

IntPending : boolean; 

TxBufferEmpty : boolean; 

DCD : boolean; 

SyncHunt : boolean; 

CTS : boolean; 

TransmitUnderRun : boolean; 

BreakAbort : boolean; 

{ Read Special Condition - SIO Chip's Read Register #1 } 
AllSent : boolean; 
Residue : Bit3; 
ParityError : boolean; 
RxOverRun : boolean; 
CrcFramingError : boolean; 
EndOfFrame : boolean; 
end; 

FloppyResultType = (NoStatus, {no status available} 

HeadChange, {status from Seek or Recalibrate} 
DriveSense, {status from SenseDrive} 
CmdResults {status from other drive cmds} 

); 

FloppyResultStatus = packed record 

{ Floppy device status is always returned as part } 
{ of the result phase of a cmd to the controller. } 
{ Z80 simply maintains a copy of the status results} 
{ for the last cmd. } 

StatusType: FloppyResultType; 
Unused : Bit6; 
case FloppyResultType of 
NoStatus: ({nothing}); 
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HeadChange, DriveSense, CmdResults: 
(Unit: Bit2; 
Head: Bitl; 

case FloppyResultType of 
DriveSense: 

(TwoSided : boolean; 

AtTrackO : boolean; 

DriveReady : boolean; 

WriteProtected: boolean; 

DriveFault : boolean 

); 

HeadChange, CmdResults: 
(NotReady : boolean; 
EquipFault: boolean; 
SeekEnd : boolean; 
IntrCode : (Normal, Abnormal, 

InvalidCmd, DriveRdyChange); 
case FloppyResultType of 
HeadChange: 

(PresentCylinder: Bit8); 
CmdResults: 
(NoAddrMark : boolean; 

NotWritable : boolean; 

NoData : boolean; 

Unusedl : Bitl; 

Overrun : boolean; 

DataError : boolean; 

Unused2 : Bitl; 

TrackEnd : boolean; 

NoDataAddrMark: boolean; 

BadTrack : boolean; 

ScanFail : boolean; 

ScanHit : boolean; 

WrongCylinder : boolean; 

DataCRCError : boolean; 

ControlMark : boolean; 

Unused3 : Bitl; 

CylinderlD : Bit8; 

HeadID : Bit8; 

SectorlD : Bit8; 

SectorSizeCode: Bit8 

) 



) 

end; 

IOSenseStatusBlk = packed record 
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StatusCnt: Bit8; 
case integer {IODevice} of 
1: {GPIB} 

(GPIBStatus: GPIBSenseStatus); 
2: {RS232A, RS232B, Speech} 
(SlOStatus: SlOSenseStatus); 
3: {Floppy} 

(FloppyStatus: FloppyResultStatus); 
0: {otherwise} { for generic access } 
(case integer of 
1: (StatusByte: packed array[stretch(l)..stretch(l)] 

of Bit8); 
2: (StatusWord: packed array [stretch(l)..stretch(l)j 

of integer); 
3: (SByte : packed array[stretch(l)..stretch(12) 
]ofBit8) 

) 

end; 

lOStatusBlk = packed record 

CmdIDTag : long; 

SoftStatus : integer; 

CmdBytesTransferred : long; 
DataBytesTransferred : long; 
DeviceStatus : IOSenseStatusBlk; 
end; 



const 









{ Baud rate codes for RS232. 







RSExt 


= 0; 


RS110 


= 1; 


RS150 


= 2; 


RS300 


= 3; 


RS600 


= 4; 


RS1200 


= 5; 


RS2400 


= 6; 


RS4800 


= 7; 


RS9600 


= 8; 


RS19200 


= 9; {only for RS232A} 


3.11 Routines 


The following Routines are from IOUser.pas. 
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Initio 

Initio is used to specify the port in the calling process's port space that will be used by the other interface 
routines in 10 User. Pas to accomplish the remote procedure calls to the 10 servers. The port specified serves as 
the reply port upon which the response from the server will be received This procedure should be called once 
and before any of the other routines in 10 User. Pas are used 

Call: 



Parameters: 



Results: 



Procedure InitIO(RPort: Port) 



RPort- This is a port in your process's port space. If NullPort 

is specified, then Initio will create a new port. 

Most programs find it convenient to just specify NullPort. 



None, 



IO Version 

This Junction returns a string which identifies the version number of the server. 

Call: 

Function IO.Version( 

ServPort : ServerNamePort) 
: String 



•m 



Parameters: 



Returns: 



ServPort-This is the port that identifies the IO server to which your request 
is being directed. It is the port that you obtain from the Name 
Server when you perform a Lookup to the Name Server for the desired 
IO server. 



The server's version number in string form. 



OpenIO 

Open IO is used to acquire the right to use the device managed by the selected IO server. The server grants 
access to a process by returning a port which the process then uses in the other IO calls. Some servers grant 
exclusive use to a single process and thus OpenIO performed by other processes will be rejected until the 
current process relinquishes access with the CloselO call. OpenIO will always enable the Synchronous 
interface to the server and will only enable the Asynchronous interface if a UserEventPort is specified 
Currently, the Asynchronous interface is not implemented and thus NullPort should be used here. 
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Call: 



Parameters: 



Results: 



Function OpenIO( 

ServPort : ServerNamePort; 
Var IOPort : ServerlOPort; 
UserPort : UserEventPort ) 
: GeneralRetura 



ServPort-Thls is the port that identifies the 10 server to which your request 
is being directed. It is the port that you obtain from the Name 
Server when you perform a LookUp to the Name Server for the desired 
10 server. 

lOPort-This is the port returned by the server 

(if the OpenIO request is 

granted) which the caller uses to make subsequent 10 requests. 

UserPort-This is the port upon which the calling 

process wishes to receive 

Asynchronous events. This port should be set to NullPort until the 

AsyncIO call is implemented. NullPort directs the server to not 

enable the Asynchronous interface. 



IOSuccess-\f the request is granted. 

IODeviceNotFree-if an exclusive-use device is already allocated. 
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CloselO 

CloselO is called when you are through using the device managed by the selected server. The specified 
ServerlOPort identifies to which server the CloselO is being directed 

Call: 

Function CloseIO( 

IOPort: ServerlOPort) 
: GeneralReturn 



Parameters: 



lOPort-This is a ServerlOPort that uniquely identifies the server to which 
the CloselO is directed. The port to use here is the ServerlOPort 
returned by the server in the OpenIO call. 



Results: 
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IOSuccess-if no errors; otherwise returns an 
identifying error code. 
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SyncID 

SyncIO is the primary call to be used in performing actual 10 operations on the device managed by the 
selected 10 server. The specified ServerlOPort identifies the server to which the request is directed. The other 
parameters are specified according to the particular requirements for the device and the valid set of commands 
applicable to the device. These are discussed in more detail in other parts of this document and are also 
presented in the module IODefs.Pas. The server performs the operation and the SyncIO call returns whenever 
the operation completes or times out. A device dependent status block is returned which shows the degree of 
success in the completion of the operation. The set of 10 error codes as well as the status block definition can 
also be found in IODefs.Pas. In most cases the server will automatically issue a device reset when an operation 
times out. For calls that don't involve the return of data, the server will always set the DataBuf parameter to 
Nil. Thus you must be careful about the parameter you supply for DataBuf so that you don't lose your 
reference to a piece of memory inadvertently. 



Call: 



Parameters: 



Function SyncIO( 

IOPort : ServerlOPort; 

Command : IOCommand; 

CmdBlk : Pointer; 

CmdBlk _Cnt : Long; 
Var DataBuf • : Pointer; 
Var DataBuf_Cnt : Long; 

DataTransf erCnt : Long; 

TimeOut : Long; 
Var Status : IOStatusBlk) 
: GeneralRetura 



IOPort-This is a ServerlOPort that uniquely identifies the server to which 
the CloselO is directed. The port to use here is the ServerlOPort 
returned by the server in the Open 10 call. 

Command-This is the IOCommand to perform. 

Cm dBlk-This is a pointer to the device specific command block. For most 
commands, you can create a pointer to an IOCmdBlk and just recast 
CmdBlk to point to it. For other commands (like lOWriteRegisters) 
which have an arbitrary number of command bytes, you will need to 
create a large enough buffer to accommodate your command bytes and 
set CmdBlk to point to it. You may also want to treat your command 
buffer as an IOCmdBlk for purposes of using the record field names to 
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assign the command byte values. Note that the first two words of the 
command block are always treated as a CmdldTag by the server and will 
be copied into the status block prior to return. The CmdldTag is 
primarily useful in the AsyncIO interface to the server. 

CmdBlkCnt-Va\s is the number of command bytes pointed 
to by the CmdBlk parameters. 

DataBuf-This is the pointer to the data. For commands that read data from a 
device, DataBuf should be set to Nil before the call. Upon return, 
DataBuf will point to a buffer holding the data read. When you are 
through with the buffer pointed to by DataBuf, you should use the 
InvalidateMcmory call (see the document "Kernel Interface" in this 
manual) to deallocate the buffer. For commands that write data to a 
device, DataBuf will point to your buffer of data to output. Since 
the server will always set DataBuf to Nil prior to return for 
commands that don't return input data, you must take care here not to 
lose your pointer reference to the buffer used in the call. This is 
easily done by using a generic pointer variable for DataBuf that has 
also been set to point to your output buffer. 

rintnhufCnt-IT)r\\c ic thp mirnh^r r\F \\yte*c in th*» hiiflRar ri'^ir!*"' 1 ^ **> ky F>oto ThxF TZnr 
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read commands, this is the number of data bytes the server has 
returned to you. For read commands you should set DataBuf to Nil and 
DataBuf Cnt to prior to the call. (This eliminates the overhead of 
passing useless data in the message to the server and prevents any 
potential invalid memory references.) For write commands, this is 
the number of bytes in your output buffer. 

DalaTransferCni-This is the number of bytes that you want to read/ write 
from/to the device. 

TimeOut-This is the number of microseconds that the server should wait for 
the operation to complete. A value of means to wait indefinitely. 
A negative value means to not wait (when that makes sense) and 
otherwise has the same meaning as 0. 

Slatus-This is the completion status of the operation. Included here is the 
DeviceStatus which is device dependent and may hold the values of 
device status registers when they were last obtained from the device. 
The current values are explicitly obtained when the IOSense command is 
issued. 



IOSuccess-if the operation succeeds completely; otherwise returns 
an identifying error code. If the command fails, Status can also be 
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checked for more detailed error information as well as an indication 
of how much of the command succeeded. 
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4 Name Server 

4.1 Introduction 

The Name Server provides processes with the ability to establish communications using textual names. In 

general, a process registers a Name/Port pair with the NameServer. Other processes can then ask the Name 

Server if it has a registration for a specific name. 

If a name is not registered with the local Name Server, that Name Server will broadcast a request on the 

network. If the name is registered with some other Name Server on the network, that remote Name Server 

will reply with a Port. 

At the current time the Name Server is a portion of the Message Server Process. The Message Server is 

responsible for extending InterProcessCommunication (IPC) over the network. The fact that the Name 

Server and the Message Server are the same process is transparent to a client of the Name Server. 

Communication with the Name Server is through a Matchmaker-generated interface. The port that is used 

for communications with the Name Server is NameServerPort defined in PascallniLpas. 

4.2 Functions 

The following functions are from MsgNUser.pas. 

Checkln 

Checkln is used to register a Name/Port pair with the local Name Server. 
Call: 

Function Checkln( 

ServPort : Port; 
PortsName: string; 
Signature: Port; 
PortsID : Port) 
: GeneralReturn 



Parameters: 



ServPort-The port that is used to communicate with the Name Server. 
It is NameServerPort from PascallniL 

PortsName-The name to be registered. 

Signature-This is not currently implemented. Use NullPort for this 
parameter. 

PortsID-ThQ port that is to be associated with PortsName. Clients of 

the Name Server who request a connection to PortsName will be given Send rights 

to PortsID. 
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Results: 

Success-Name was registered correctly. 
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LookUp 

LookUp is used to obtain a port that is associated with a name. 

Call: 

Function LookUp( 

ServPort : Port; 
PortsName: string; 
varPortsID : Port) 
: GeneralReturn 



Parameters: 



ServPort-Thc port that is used to communicate with the Name Server. 
It is NameServerPort from Pascallnit. 

PortsName-The name to look for. 

PortsID-The port that is to be associated with PortsName.The caller 
of LookUp will be given send rights to PortsID. 

-The port PortsName was found and PortsID contains a port 
that can be used to communicate with it. 

-The port PortsName was not found. PortsID is not 
valid. 
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Checkout 

Checkout is used to remove a Name/Port registration from the Name Server. 

Call: 

Function CheckOut( 

ServPort : Port; 
PortsName: string; 
Signature : Port ) 
: GeneralReturn 



Parameters: 



ServPort-The port that is used to communicate with the Name Server. 
It is NameServerPort from Pascallnit 
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PortsName-The name to be removed- 
PS = Signature 

-This is not currently implemented. Use NullPort for this 
parameter. 

-Name was removed 

-The client tried to remove a name that it did not 
register. 

aw»M»MH»HMJ iBinig i gim« i Bi « iH i » +»t»»«iM in i M H»»»t«4 am 

MsgPortStatus 

MsgPortStatus returns Message Server internal information about a Port. This function is a system function 
and is not for users. 
Call: 

Function Checkln( 

ServPort : Port; 

PortsID : Port; 
var GlobalPort : long; 
var Owner : long; 
var SrcID : long; 
var SeqNum : long; 
var NetWaiting : boolean; 
var NumQueued : integer; 
var Blocked : boolean; 
var Locked : boolean; 
var RecvQueue : integer; 
var DataOff set : long; 
var InSrcID : long; 
varlnSeqNum :long) 
: GeneralReturn 
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5 The Network Server 

5.1 Introduction 

The Network Server (or NetServer) provides access to the Ethernet for all processes that are running on a 
given Perq. All access to the Ethernet is through the Network Server. The CMU 3MHz NetServer provides 
access to both the 3MHz and 10MHz Ethernets. On the 10MHz Ethernet it functions by encapsulating 
3MHz Ethernet packets within 10 MHz Ethernet packets. 

Note that this 3MHz network server is unique to CMU. At other sites a 10MHz NetServer is used by Perqs 
communicating solely on a 10 MHz Ethernet. See the PERQ Systems document, The Network Server, for 
more details. 

User access to the Network Server is through a Matchmaker-generated message interface. The Network 
Server user sees a set of procedure calls. These calls are translated by Matchmaker-generated code into 
messages that are then sent to the Network Server. The Network Server will act on the request and send a 
reply to the client. The reply messages are translated by Matchmaker-generated code into a format that is 
suitable for the user. (Because the netserver used to be called the EtherServer, the matchmaker interface to 
is is called EtherUser.) 

When a user process wishes to receive packets from the Ethernet, it informs the Network Server. The user 
provides the Network Server with the type of Ethernet packets that it wishes to receive. It also provides send 
rights to a port. When an Ethernet packet is received by the Network Server the Server checks to see if any 
of its users are interested in packets of that type. If so it will send the received packet to those users in an 
IPC message. To get the message cotaining a packet, the user does an IPC receive on the port that it 
previously provided to the Network Server to get the message that contains the packet. The user then uses 
Matchmaker-generated code to obtain the actual Ethernet packet from this IPC message. 

5.2 overview 

In order to provide both synchronous and asynchronous communication with the NetServer, the functions 
provided by this module are implmented with three subroutine call each. The Send and Parse calls are to be 
used (along with a user written Receive call) for asynchronous communication. The Wait calls are to be 
used for synchronous communication. The three types of routines have following implementation: 

Send<X> This routine sends off a request message to the NetServer. It usually takes a 

reply port as^well as parameters to the function, and returns the result of the 
send call. 

Parse<X> This routine parses a request response from the NetServer. It usually takes a 

message pointer as a parameter and returns the function results as its result, or in 
var parameters, depending on the number of output variables. 

Wait<X> This routine combines the above two routines for synchronous server 

communication. It will raise an exception if something goes wrong. The 
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exceptions are defined below. It should be pretty obvious what their arguments 
refer to. 

All the routines implicitly take the NetServer port as a parameter. This port is hidden withing the 
EtherUser module and is initialised when the routine InitEther is called. 

The netserver supports two types of packet format: raw 3Megabit ether packets, and pup packets. Thus 
there are parallel sets of calls depending on which packet format is desired. 

53 Initializing the interface 

The procedure InitEther must be called before other routines can be executed. 
Example: 

InitEther (NullPort, 0); 

5.4 Getting the Ethernet Address of the Machine 

The Network Server user must place the Ethernet address of the current machine into the Source field of 
the Ethernet packet header. The Network Server provides facilities to get the Ethernet address from the 
Ethernet hardware. The address that is returned is in a form that can be placed directly into an address field 
of an Ethernet header. The CMU MHz network server always returns a 3MHz address even thought the 
machine may be on the lOMhz ethernet 

Example: 

VAR 

host : integer; 

BEGIN 

host := WaitEtherAddress; 

writeln ('My host = ', host:l); 

5.5 Sending an Ethernet Packet 

To send a packet on the Ethernet, the user must set the Ethernet packet header to contain the destination 
address, the correct source address and the packet type fields of the header. The packet can be sent using 
SendEtherPacket 

5.6 Connecting to an Ethernet Type 

To receive packets from the network, the user process must tell the Network Server that it wishes to receive 
packets of a specific Ethernet type on a user-provided port. The Ethernet type acts as a filter within the 
network server. It is possible to receive packets of more than one Ethernet type on a single port by making 
multiple calls to WaitEtherFilter with different filters but with the same port. 

Example: 
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VAR 



filter 
retval 
ok 
myport 



integer; { Packet type } 

GeneralReturn; 

boolean; 

port; 



BEGIN 

retval := AllocatePort (KernelPort, myport, Def aul tBacklog) ; 

Write ('Filter number: *); 

Readln (filter); 

ok := WaitEtherFil ter (myPort, filter); 

5.7 Type Definitions 

The following definitions are from EtherTypes.pas. 

CONST { return codes from PerqE3, PerqElO, PorkE3 } 

IOEIOC = #0; { successful } 

IOETIM = # 1; {no packet is being returned from Ethcr3Receive } 
IOEPTL = #2; {a packet > WdCnt has been received } 
IOERNT = #3; { a packet < WordSize(EtherHeader) has been received } 
IOEBSE = #4; { WdCnt > E3BufferSize } 
IOEFUZ = #5; { packet length not integral number of words } 

TYPE 

EtherHeader = PACKED RECORD 
Src : 0..255; 
Dst :0..255; 
Typ : INTEGER; 
END; 

CONST 

MinEtherWords = WordSize(EtherHeader); 

MaxEtherWords =748; { 750 words max data size on lOmhz net, but 2 

words are needed for the 3hmz encapsulation 

header on the lOmhz net. } 
{ 560 is the vax 3mhz limit (ENETPACKETSIZE)} 

TYPE 

pEtherPacket = tEtherPacket; 
EtherPacket = RECORD 
CASE Integer OF 
0:( 

Header : EtherHeader; 
DataWords : ARRAY[0 .. MaxEtherWords - 
WordSize(EtherHeader) - 1 
] OF INTEGER); 

1:( 
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Words : ARRAY[0 .. MaxEtherWords- 1] OF INTEGER ); 

2: ( 

LongHeader : EtherHeader; 
LongWords : ARRAY[0 .. (MaxEtherWords - 

WordSize(EtherHeader)) 

div2- 1] OF LONG); 

3:( 

ConfigHdr : EtherHeader; 
SkipC : integer; 
ConfigBytes : PACKED ARRAY 

[0 .. 2 *(MaxEtherWords - 
WordSize(EtherHeader) - 1)] 
OFBit8) 
END; 



CONST 

EtherTypEehoMe = #700; 
EtherTypIAmAnEcho = #701; 
EtherTyp3ConfigTest = #220; 
EtherTypPup = #1000; 
EtherTypConfigTest = #220; 

FwdCode = 2; 

RepiyCode = 1; 

TYPE 
PupLLong = RECORD 

CASE INTEGER OF 
1 : ( Lng : Long ); 
2 : ( Low : Integer; 
Hgh : Integer ) 
END; 

TYPE 
PupHLong = RECORD 

CASE INTEGER OF 
1 : ( Lng : Long ); 
2 : ( Hgh : Integer; 
Low: Integer); 
END; 



TYPE 

PupPort = PACKED RECORD 

CASE integer OF 

0:( 

Host: 0.. 255; 
Net :0.. 255; 
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Soc : PupHLong ); 

1:( 

All j PACKED ARRAY [0..5] OF Char ) 
END; 


TYPE 




PupHeader 


= PACKED RECORD 
Len : INTEGER; 




Typ : 0.. 255; 
TC : 0.. 255; 




Id : PupHLong; 
Dst : PupPort; 
Src : PupPort 
END; 


TYPE 




pPupData 
PupData 


= tPupData; 
= RECORD 



CASE INTEGER OF 

: (Chars : PACKED ARRAY[ 0..1043] OF CHAR); 

1 : (Bytes : PACKED ARRA Y[ 0..1043] OF 0..255); 

2 : (Words : PACKED ARRAY[ 0.. 521] OF INTEGER); 

3 : (HLongs : PACKED ARRAY[ 0.. 260] OF PupHLong); 

4 : (Ports : PACKED ARR AY[ 0.. 260] OF PupPort); 
END; 



CONST 

MinPupWords 
MaxPupWords 



= WordSize(PupHeader) + 1; 
= 533; 



TYPE 

pPupPacket = tPupPacket; 
PupPacket = RECORD 

CASE INTEGER OF 

: ( Header : PupHeader; 

Data : PupData ); 
1 : ( ChkSums : ARRAY [0..532] OF Integer ) 
END; 



CONST 
PupCMUNet 


= #52; 


CONST 
PupError = 


#4; 


PupEFTPData 
PupEFTPAck 


= #30; 
= #31; 
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PupEFrPEnd = #32; 
PupEFTPBort = #33; 

CONST 

PupNameSocket = #4* #200000; {word- swapped longs} 
PupEFTPSocket = #20*#200000; 

TYPE 
MsgPacket = RECORD 

Head : Msg; 

TPacket :TypeType; 

END; 

MsgEtherPacket = RECORD 
Head : Msg; 

TPacket : TypeType; 

Packet : EtherPacket; 

END; 

MsgPupPacket = RECORD 
Head : Msg; 

TPacket : TypeType; 

Packet : PupPacket; 

END; 

CONST 

PacketBytes = 2 * WordSize(MsgPacket); 
EtherPacketBytes = 2 * WordSize(MsgEtherPacket); 
PupPacketBytes = 2 * WordSize(MsgPupPacket); 

CONST 
EtherlDBase = 800; 

IDGetEthcrAddress = EtherlDBase + 1; 
IDRGetEtherAddress = EtherlDBase + 101; 

IDSetEtherFilter = EtherlDBase + 2; 
IDRSetEtherFilter = EtherlDBase + 102; 

IDClrEtherFilter = EtherlDBase + 3; 
IDRClrEtherFilter = EtherlDBase + 103; 

IDSendEtherPacket = EtherlDBase + 4; 
IDRecvEtherPacket = EtherlDBase + 104; 

IDSetPupFilter = EtherlDBase + 5; 
IDRSetPupFUter = EtherlDBase + 105; 
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IDClrPupFilter = EtherlDBase + 6; 
IDRClrPupFilter = EtherlDBase + 106; 

IDSendPupPacket = EtherlDBase + 7; 
IDRecvPupPacket = EtherlDBase + 107; 

TYPE 

pMsgGetEtherAddrcss = tMsgGetEtherAddress; 
MsgGetEtherAddress = RECORD 
Head : Msg 
END; 

pMsgRGetEtherAddress = tMsgRGetEtherAddress; 
MsgRGetEtherAddress = RECORD 

Head : Msg; 

TEtherAddress : TypeType; 

EtherAddress : INTEGER 
END; 

pMsgSetEtherFilter = tMsgSetEtherFilter; 
MsgSetEtherFilter = RECORD 

Head : Msg; 

TTyp : TypeType; 

Typ : INTEGER; 

TProcessPort: TypeType; 

ProcessPort : Port 
END; 

pMsgRSetEtherFilter = tMsgRSetEtherFilter; 
MsgRSetEtherFilter = RECORD 



Head 


:Msg; 


TTyp 


: TypeType; 


Typ 


: INTEGER; 


TAnswer 


: TypeType; 


Answer 


: BOOLEAN 


END; 




pMsgClrEtherFilter = 


tMsgClrEtherFilter; 


MsgClrEtherFilter = 


RECORD 


Head 


: Msg; 


TTyp 


: TypeType; 


Typ 


: INTEGER; 


TProcessPort: TypeType; 


ProcessPort : Port 


END; 





pMsgRClrEtherFilter = tMsgRClrEtherFilter; 



27 Aug 84 



Servers-57 



MsgRClrEtherFilter = RECORD 



Head 


: Msg; 


TTyp 


: TypeType; 


Typ : 


INTEGER; 


TAnswer 


: TypeType; 


Answer 


: BOOLEAN 


END; 





pMsgSendEtherPacket = tMsgSendEtherPacket; 
MsgSendEtherPacket = MsgEtherPacket; 

pMsgRecvEtherPacket = tMsgRecvEtherPacket; 
MsgRecvEtherPacket = MsgEtherPacket; 

pMsgSetPupFilter = tMsgSetPupFilter; 
MsgSetPupFilter = RECORD 

Head : Msg; 

TSocket : TypeType; 

Socket : Long; 

TProcessPort: TypeType; 

ProcessPort : Port 
END; 



pMsgRSetPupFilter = 


: tMsgRSetPupFilter; 


MsgRSetPupFilter = 


RECORD 


Head 


: Msg; 


TSocket 


: TypeType; 


Socket 


: Long; 


TAnswer 


: TypeType; 


Answer 


: Boolean 


END; 




pMsgClrPupFilter = 


tMsgClrPupFilter; 


MsgClrPupFilter = 


RECORD 


Head 


:Msg; 


TSocket 


: TypeType; 


Socket 


:Long; 


TProcessPort: TypeType; 


ProcessPort : Port 


END; 





pMsgRClrPupFilter = tMsgRClrPupFilter; 
MsgRClrPupFilter = RECORD 

Head : Msg; 

TSocket : TypeType; 

Socket : Long; 

TAnswer : TypeType; 
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Answer : Boolean 
END; 

pMsgSendPupPacket = tMsgSendPupPacket; 
MsgSendPupPacket = MsgPupPacket; 

pMsgRecvPupPacket = tMsgRecvPupPacket; 
MsgRecvPupPacket = MsgPupPacket; 

5.8 Exported Exceptions 

Exception ESendFailed(Why: GeneralReturn); 
Exception EReceiveFailed(Why: GeneralReturn); 
Exception EBadReply; 

5.9 Common Parameters 

GeneralReturn The return code from the Send Kernel call. 

Listener The port to which to send the notification that a reply to this call has been 

received. 

MaxWait Maximum number of milleseconds to wait for a send to NetServer to complete. 

The value means wait forever. 

MsgP A pointer to a specific type of message. 

Option Send option for the Send call. Specifies what to do if the server queue is full. 

Values are wait,dontwait, and reply. 

packet A pointer to a pup packet 

Reply Port to which reply to this message is to be sent 

Typ A filter specifying the types of ethernet packages that are to be listened for. The 

values for this parameter are exported by ethertypes.pas. 

socket The local part of a pup protocol EtherNet address. This acts as a filter for pup 

tranmission. 

5.10 Procedures 

The following procedures are found in EtherUser.pas. 

"InitEther" 

This procedure sets up vital state information for the interface and must be called before any of the other 
routines are used 
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Call: 



procedure InitEther( 

RPort :port; 
Heap : integer) 



Parameters: 



"Rport"-port to which replies from the Ether Server should be 
sent If it is equal to NullPort, a new port is allocated. 



Exceptions: 



"Heap' -heap to be used for dynamic storage allocation. If 
equal to 0, the default data heap is used. 



""-Exceptions raised by the 'wait' routines, should be obvious, if not 
check the code. 



a i anaiain i a ia i a iaiaiaiaiaiaiaiaiaia i niaia i aiaimaiaiaiaiBIMIBMaiaiainnMiai 

"SendEtherAddress" 

Send a message to find out the local EtherNet address 

Call: 

function SendEtherAddress( 
Reply :Port; 
Max Wait: long; 
Option : SendOption ) 
: GeneralRetu'rn 

BiainiaiBia i llli a iMia i a iaiai g i ai Bi ai a iniB C iaiB I BIB IB IBI B iBia i C I Ki a i B ia i Biaia i 

"ParseEtherAddress" 

Parse the reply message containing the EtherNet address 

Call: 

function ParscEthcrAddress( 

MsgP :pMsgRGetEtherAddress ) 
:integer 

Returns: 

EtherNet address 



■ IBimB i mBIBiMIP I BlBIBI B I BI B I BIBia i BIBlBIBIB i amiBIBlBIBIBIHI Bi n iB IBa i E3iai 

"WaitEtherAddress" 



Synchronously get the EtherNet address 
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Call: 

function WaitEtherAddress : integer; 
Returns: 

EtherNet address 

BIBIH I «I BI B I BI B IBI B I « ia i M I«IB I W iai B I M I « IW IB I«l«l » l»I M I Mi ai « l «I M I «IB 'BI"l« l ■ 

"SendEtherFilter" 

Send a message to set the ether filter - 
Call: 

function SendEtherFilter( 

Typ : integer; 
Listener : Port; 
Reply : Port; 
Max Wait : long; 
Option : SendOption) 
: GeneralReturn 

A ether filter specifies the type of ether packets that we are interested in listening for. After a filter with the 
value of Typ has been set, any incoming packets of that type cause a notification message to be sent to the 
Listenerport 

■ I Bi l BllBi l BllBI I BI I BllBllBiiaiBllBllBl l BllBllB il Bi i BllMIBilBIIBilBllBllBllllBilBilBIII I Bli n i M l g l MI MI ■ 

"ParseEtherFilter" 

Parse reply message containing value of ether filler. 
Call: 

function ParseEtherFilter( 

MsgP : pMsgRSetEtherFilter; 
varTyp : integer) 

:boolean; 

Returns: 

true - if the ether filter of the value Typ has been set 

false - if the filter was not set because the maximum number 
of filters was already set. Currently the maximum number of 
filters is 4. 

■ IBllBilBliniHil B ilBIIBllBllBIIBii a iBllBII Bl lBllB!IWIB I IBil B IIB!IBllBllBilBII B i lB i l Bll1l1l 1i g i 1 l1 l1» ■ 

"WaitEtherFilter" 

Synchronously set a new value for the ether filter 
Call: 
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function WaitEtherFilter( 

Typ : integer; 
Listener : Port ) 
: boolean; 

Returns: 

same as for ParseEtherFilter. 

■ IM I M i m M l M lMi n i Mi n il W IMIM IM IMI MIMi nini l M IMlC a i MIMI M IMIMi a i l MIMII IWllZ i e ai B il lieB I ■ 

"SendEtherClear" 

Send message to remove an ether filler 

Call: 

function SendEtherClear( 

Typ : integer; 
Listener : Port; 
Reply : Port; 
Max Wait : long; 
Option : SendOption ) 
iGeneralRetura; 

Removes the filter of value Typ with the associated notification port of Listener. 

■ I BIBI B in iB I B IBI B I BmiP I B I B I BiSIMI BI BIB i aSIBIg l BIB IB iniBilBI BI BiniHl B IBIBm i a 

"ParseEtherClear" 

Parse message received as a result of an EtherClear message 

Call: 

function ParseEtherClear( 

MsgP : pMsgRClrEtherFilter; 
var Typ : integer ) 
: boolean; 

Returns: 

"same as for ParseEtherClear. " 

■ IBIBI BIOH B IB IB IB IB IHI BIB I BI B I B I B IBi B IBIB I BI BI B IB I B I B IBI BIB I BI BI BI BI B IB ini ■ 

"SendEtherPacket" 

Send an ethernet packet pointed to by 'Packet', of size 'PackelWords' 

Call: 

function SendEtherPacket( 

Packet : pointer; 
PacketWords: integer; 
MaxWait : long; 
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Option : SendOption ) 
: GeneralReturn; 

Parameters: 

"Packet "-pointer to packet to be sent 

"PacketWords "-number of words in packet. 

n i « I M I B I«I B IB Ha iBllBI ■! ■ !■! ni n i B IBIBI B I ll lBIB I BI MIB I P I Bf lBi aiE I- I BIBIB H ai ia i M 

"ParseEtherPacket" 

Copies an eihernet packet from the response message into the area pointed at by 'Packet', returning the 
number of words copied. 

Call: 

function ParseEtherPacket( 

MsgP : pMsgRecvEtherPacket; 
Packet : pointer) 

: integer; 

Parameters: 



Returns: 



"Packet "-Pointer to packet to be parsed. 
number of words in packet 

■ [ ■ I HIWIMIM I MIMiniBIHIHIM m iM m i M IMIPIIHIMIHIM I BIBi a iM I MIIll W l l ia i HI B IBllBI B I ■ 

"SendPupFilter" 

Add a new socket on which to receive pup packets. 

Call: 

function SendPupFilter( 

Socket : Long; 
Listener : Port; 
Reply : Port; 
Max Wait : long; 
Option : SendOption ) 
: GeneralReturn; 
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"ParsePupFilter" 

Parse return message from SendPupFilter call 
Call: 
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function ParscPupFilter( 

MsgP : pmsgrsetpupfi Iter; 
var Socket : Long ) 
: boolean; 



Returns: 



true - if the socket has been added to the list of available sockets. 

false - if the socket was already in use, or if the maximum number of 
sockets was already allocated. Currently, the maximum number of sockets 
is 4, 



B a H IB IBIB i Pia i g i B I MIBl B I B BI B I»IB I B I B5 IMi nin i M i BlHl Pi l B lMin i HIM I M IBI » l1I IB I BI «l ■ 

"WaitPupFilter" 

Synchronously add a new socket on which to receive pup packets. 

Call: 

function WaitPupFilter( 

VAR Socket : Long; 
Listener : Port ) 
: boolean; 

Returns: 

same as for ParsePupFilter. 

"SendPupClear" 

Send message to deallocate a socket 

Call: 

function SendPupClear( 

Socket : Long; 
Listener : Port; 
Reply : Port; 
MaxWait : long; 
Option : SendOption ) 
: GeneralReturn; 

■ ■■ I MIM I 1l g lWI1IHIWIWIB I WIBIMI M IM I BI«I M I«IW i W I M I I« ai WIWIWIBiniWlBIMIWIffl i lH I M I ■ 

"ParsePupClear" 

Parse message reply from SendPupClear message. 
Call: 
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function ParscPupClear( 

MsgP : pMsgRClrPupFilter; 
var Socket : Long ) 
: boolean; 

Returns: 

true - if the socket was found and deallocated. 

false - if the socket was not found 

"WaitPupClear" 

Synchronous call to allocate a pup socket. 

Call: 

function WaitPupClear( 

var Socket : Long; 
Listener : Port ) 
: boolean; 

Returns: 

same as for ParsePupClear 

■ ■■iMi B iniBiBiHiMi»iaiMiMiMiBini«iBiBiaia in i« i Mi a iaigi Bm iMi Mi niBi«iMiMiw i 

"SendPupPacket" 

" Send a Pup Packet pointed to by 'PupPacket*. " 

Call: 

"function SendPupPacket( 
PupPacket : pointer; 

MaxWait : long; 
Option : SendOption 

: GeneralRcturn;" ) 

"ParsePupPacket" 

Copies the Pup packet from the PacketMessage into the 'PupPacket*. 

Call: 

procedure ParsePupPacket( 

MsgP : pMsgRecvPupPacket; 
PupPacket : pointer); 
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"FinEther" 

Deallocate resources allocated for local use. 
Call: 

procedure FinEther; 
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6 Process Manager 

6.1 Introduction 

The Process Manager controls and monitors the activity of a process. It supplements the process control 
functions of the Accent kernel. Process control signals can be sent between processes to control individual 
or groups of processes. The user can also suspend, resume, cancel and debug processes through shell or 
Window Manager commands. 

To use the Process Manager a process must be rgistered. If the process was created with Spawn it it 
automatically registered otherwise a process can be registered with the function PMRegistcrProcess. A 
process that is not registered with the Process Manager will be harder to start up and impossible to control. 

6.2 Process Trees 

Processes are organized into trees. Each process in the tree has a parent and a set of children. Registering a 
process supplies the Process Manager with: 

• the parent of the process. 

• the kernel and data ports of the new process, 

• a descriptive name for the process, 

• the window, typescript and environment manager connections, 

The parent process controls the children through Accent or the Process Manager. The parent is notified 
when a child dies through an emergency message that contains 

1. the reason for termination - "process death" if the child gives no reason 

2. run time - if available 

3. load time - if available 

4. elapsed time - if available 

A process may reregister itself with a new parent. When a parent dies surviving children are "orphans". 

63 Process Control Groups 

Processes can be controled together through Process Control Groups. Each window can only belong to one 
process group. A group can be associated with one or more windows and a process cotnrol key typed to any 
window affects all of the process group. The name of the group is located in the window icon (aliases for the 
name are in icons of other windows in the group). If a process changes it's group, it's children become 
members of the new group. If the process control window is removed, the process is "out of control" and 
can only be controlled by shell process control commands. 
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6.4 Process Control Signals 

The Process Manager provides 64 Process Control Signals, 7 with defined roles: 

Signal Default Action 

suspend suspend the process 

resume resume the process 

status display status in process manager window 

LevellAbort terminate process 

Level2Abort terminate process 

LeveBAbort terminate process 

debug suspend process & invoke debugger 

other ignore signal 

On receiving a signal a process may 

1. Send - send an emergency message saying what signal has occured (resume any suspended 
processes). 

2. Ignore - ignore signal. LeveBAbort signals cannot be ingored and will terminate the process. 

3. Default - perform the default action for the signal. 

The action for each signal may be specified independently. There are Process Manager functions 
(Emergency Messages) to send a signal to an entire process group or single process in a group. 

6.5 Keyboard and Window Manager control 

The following commands can be typed to the shell to control processes, 

Suspend <string> 
Resume <string> 
Debug <string> 
Kill <string> 
SetPriority <string> 

If the string given is a group name the command will affect the group. The command will affect a process if 
the string given is a process number or a prefix of the process name. If the string matches more than one 
process name the command fails and returns NameAmbiguous. 

These same commands can be selected from the Window Manager menu or with the Window Manager 
keyboard commands. See the User's Guide to the Window Manager for more information. 

6.6 Debugging 

The process manager can register a debug port for a process. If the process gets an uncaught exception or an 
addressing error, or if a signal is raised and not caught, the process is suspended and an emergency message 
is sent to the debug port (This is line AccInt.SetBugPort in the kernel, but intercepts signals as well as 
program errors.) The port may be set up to catch all uncaught signals or only the Debug signal. A debugger 
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can use this to keep control of a process and to intercept subsequent Debug keys (instead of starting up 
another debugger). 

The global Environment variable "DebuggerName" is the name of the debugger to run. When the 
debugger is invoked, the Process Manger first tries to run the program named in "DebuggerName". If that 
is not found, it tries to run 'Debugger.run'. If that, in turnis missing, it runs the built-in Mace debugger. If 
"DebuggerName" has the value '?' the Process Manager asks the user for the name of a run file to run as 
the debugger. 

The debugger starts up with the following environment: 

InPortst[0] Kernel Port of target process 

InPortstjl] Process Manager Port 

EMPort process Environment Manager connection for target 

UserWindow, Window and typescript for the debugger. 

UscrTypescript Process control functions on this window affect 

the Debugger, not the target process (the 

debugger may, of course, intercept them). 

6.7 Definitions 

The following definitions are found in ProcMgrDefs.pas , 

Const 

ProcMgrBase = 3600; { Process Manager messages and errors } 
SignalBase = 3800; { Signals and asynchronous returns } 

{ Error returns from ProcMgr } 

UnknownProcess = ProcMgrBase +1; 

UnknownSignal = ProcMgrBase +2; 

UnknownAction = ProcMgrBase +3; 

UnknownWindow = ProcMgrBase +4; 

WindowInUse = ProcMgrBase +5; 

NoChildren = ProcMgrBase +6; 

UnknownPort = ProcMgrBase + 7 ; { NullPort given to ProcMgr } 

Name Ambiguous = ProcMgrBase +8; 

ProcessDisowned = ProcMgrBase +9; 

{ Signals } 

MinSignal = SignalBase; 
MaxSignal = SignalBase +63; 

{ signal numbers 1..32 are reserved for Spoonix! } 

SigSuspend = MinSignal +33; 
SigResume = MinSignal+34; 
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SigStatus = MinSignal+35; 
SigDcbug = MinSignal+36; 
SigLevell Abort = MinSignal+37; 
SigLevel2Abort = MinSignal+38; 
SigLeveB Abort = MinSignal+39; 

type 

SignalName = integer; 



{ Actions } 
type 

SignalAction = (SigDefault, 

Siglgnore, 

SigSend); 



{ Statistics returned to caller } 

StatRecord = record 

RunTime: long; {microseconds} 
LoadTime: long; { microseconds } 
ElapsedTime: long; {ticks} 
KernelPort: long; { number, not port } 
Priority: integer; 
QueuelD: integer; 
ProcName: string; { Process name } 
IconName: ProgStr;{ name in Icon - group name } 
State: ProcState; 
end; 

StatArray = array[0..0] of StatRecord; 
StatList = tStatArray; 

6.8 Functions 

The following functions are found in ProcMgrUser.pas. 
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PMRegisterProcess 

Register a process with the Process Manager 
Call: 

function PMRegisterProcess( 

ServPort : Port; 
HisKPort : Port; 
HisDPort : Port; 
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ProgName : string; 
HisWindow : Window; 
HisTypescript: Typescript; 
EMConn : port; 
Parent : port) 
GeneralReturn 



Parameters: 



ServPort-Pon to Process Manager (exported by Pascallnit as PMPort). 

HisKPort-Thc kernel port of the process to be registered. 

HisDPort-ThQ data port of the process to be registered. 

ProgName-Thz name of the process, usually the .RUN file name. 
Spawn registers the parameter that it calls ProcName as the ProgName. 

HisWindow-The window associated with the process. NullPort if none. 

HisTypescript-The typescript associated with the process. 

EMConn-The port associated with a new connection to the 
Environment manager for this process. NullPort if none. 

Parent-The kernel port of the Parent Process. 

The supplied data is entered into the Process Manager Data Base and the icon name for the process's window 
is set to be ProgName. 
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PMSetSignal 

Set the signal actions for a process 

Call: 

function PMSetSignal( 

ServPort : port; 
ProcPort : port; 
Signal : SignalName; 
Action : SignalAction) 
: GeneralReturn 



Parameters: 



ServPorl-Poit to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-The Kernel port of the process to affect 
Signal-Signal to change action for. 
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Results: 



Action-New Action to set for signal. Actions are: 

SigSend - send a SignalMessage to the process's SignalPort 
with the signal as the reason. 

Siglgnore - completely ignore the signal. 

SigDefault - take the default action for the signal. 

Success 

UnknownProcess 
UnknownSignal 
Unknown Action 
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PMSetSignalPort 

Sets the signal port (port to receive signal message for SigSend) for a process. 

Call: 

function PMSetSignalPort( 

ServPort : port; 
ProcPort : port; 
SignalPort : port ) 
: GeneralReturn 

Parameters: 

ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcPort-The Kernel port of the process to affect 
SignalPort-The port to receive SignalMsg 

PMSetDebugPort 

Sets up a port to intercept errors and default signals for a process. If the debug port exists, the default action 
for the debug signal (or all signals) will be to suspend the process and send a message to the debug port. In 
addition, the debug port will receive all Debug error messages for the process (from the kernel). 

Call: 
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function PMSctDcbugPort( 

ScrvPort : Port; 
ProcPort : Port; 
DebugPort : Port; 
DcbugSignalOnly : Boolean) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcPort-The Kernel port of the process to affect. 

DebugPort-Port to receive emergency message when something happens 
to the process. 

DebugS ignalOnly-lf 'TRUE, only intercept uncaught DEBUG signals. 
If FALSE, intercept ALL uncaught signals. 

Success 

UnknownProcess 

The 'SetDebugPort' call in Accent only intercepts exceptions and memory faults. This call intercepts Signals* 
as well. 
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PMSaveLoadTime 

Saves the load time for a process so that it can be printed later. 

Call: 

function PMSaveLoadTime( 

ServPort : Port; 
ProcPort :Port; 
LoadTime : long) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Pon to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-Kemel port of process. 
LoadTime-Time to load process (microseconds) 

Success 
UnknownProcess 
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PMGetWaitID 

Get the Wait ID' of a child process. The Wait ID is a 32-bit number that is returned when the child process 
dies. Its only use is to identify the dead process (the dead process' KernelPort is no longer valid, since it was 
deallocated when the process died). 
Call: 

function PMGetWaitID( 

ServPort : Port; 
ProcPort : Port; 
var WaitID : long) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-Kcrnol port of process. 
Waj7/Z)-returns the Wait ID for the child process. 

Success 



UnknownProcess 
The 'processdeath' message is returned to the parent's DataPort, whether or not it has asked for the child's 
WaitID. 

PMGetTimes 

Returns the run and elapsed time for a process. 
Call: 

function PMGetTimes( 

ServPort : Port; 

ProcPort : Port; 

varLoadTime : long; 

var RunTime : long; 

var ElapsedTime : long) 

: GeneralReturn 

Parameters: 

ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcPort-Kernel port of process. 
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Results: 



LoadTime-RQtums the load time for the process (microseconds). 
RunTime-Returns the run time for the process (microseconds). 
ElapsedTime-Returns the elapsed time for the process (1/60 second). 

Success 
UnknownProcess 
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PMGetProcPorts 



Get the registered ports of a process. 
Call: 



Parameters: 



Results: 



function PMGetProcPorts( 

ServPort : Port; {get ports for process being 
ProcPort : Port; debugged} 
var hisWindow : window; 
var histypescript : typescript; 
var hisEMConn : Port) 
: GeneralReturn 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-KQTnel port of process. 
hisWindow-retums window 
hisTypescript-rctums typescript for process. 
hisEMConn-vetarns Environment connection for process. 

Success 
UnknownProcess 
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PMTerminate 



Terminate a process. 
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Call: 



Parameters: 



Results: 



function PMTerminate( 

ServPort : Port; 
ProcPort : Port; 
Reason : long) 
: GeneralReturn 



ServPorl-Port to Process (exported by Pascallnit as PMPort). 
P roc Port-Kernel port of process. 
Reason-Reason for termination. 

Success 
UnknownProcess 
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PMDebugProcess 

Invoke a debugger on a process. 
Call: 

function PMDebugProcess( 

ServPort : Port; 
ProcPort :Port; 
Reason : long) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Pon to Process Manager (exported by Pascallnit as PMPort). 
Proc/to-Kernel port of process. 
Reason-Reason for debugging process. 

Success 

UnknownProcess 

Failure-couldn't invoke debugger 
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PMAddCtlWindow 

Add a new window to the set of controlling windows for a process group. 

Gall: 

function PMAddCtlWindow( 
ServPort : Port; 
CtlWindow : Window; 
NewCtlWindow : Window) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Voxt to Process Manager (exported by Pascallnit as PMPort). 
CtlWindow-an existing window for a control group. 
NewCtlWindow-a new window to add as a control window. 

Success 

UnknownWindow-CtlWmdow is not a control window for a process group. 

UnknownPort-NewCiLWmdovf is NullPort. 
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PMRemoveCtlWindow 

Removes a window to the set of controlling windows for a process group. 

Call: 

function PMRemoveCtlWindow( 
ServPort : Port; 
CtlWindow : Window) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
CtlWindow-an existing window for a control group. 

Success 

UnknownWindow-CilWmdov/ is not a control window for a process group. 
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PMChangeGroup 

Changes a process (and its descendants) to a new process group. If there is already a process in the process 
group, it must be the parent of the affected process. 

Call: 

function PMChangeGroup( 
ServPort : Port; 
ProcPort : Port; 
NewWindow : Window) 
: GeneralReturn 



Parameters: 



Results: 



Serv Port-Port to Process Manager (exported by Pascal Init as PMPort). 
ProcPort-Kemel port of process. 
Window-Window to use for new group. 

Success 

UnknownProcess 

UnknownPort-if window is NullPorL 

Windowln Use-window already controls a process group. 
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PMGroupSignal 

Removes a window to the set of controlling windows for a process group. 

Call: 

function PMGroupSignal( 

ServPort : Port; 
CtlWindow : Window; 
Signal : SignalName) 



M-a 



Parameters: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
CtlWindow-One of the windows controlling a process group. 



Signal-Signs! to send. 
This is an Emergency message to the process manager. 
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PMProcessSignal 

Sends a signal to a single process. 
Call: 



function PMProcessSignal( 
ServPort : Port; 
ProcPort : Port; 
Signal : SignalName) 



Parameters: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcPort-Kernel port for a process to signal. 

Signal-Signal to send. 
This is an Emergency message to the process manager. 

B IBIBIBIB IB IBIBI B IBI BI BIBIHIBIBIBI B IBininiBI B I B IBlBIBIBIB I B in ia n ni BiniB l in i ■ 

PMSuspend 

Suspend a named (or numbered) process. 
Call: 

function PMSuspend( 

ServPort : Port; 

ProcID : string) 
: GeneralReturn 



Parameters: 



ServPort-Poit to Process Manager (exported by Pascallnit as PMPort). 

ProcID-Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 



Results: 



Success 
UnknownProcess 

NameAmbiguous 

If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
a single process, it suspends the process. If the process has a DebugPort set, it also send an M_DebugMsg 
message to the debug port, with SigSuspend as the reason (unless the debug port is set to DebugSignalOnly). 
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PMResume 

Resume a named (or numbered) process. 
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Call: 



Parameters: 



function PMSuspend( 

ServPort : Port; 
ProcID : string) 
: GeneralReturn 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

Proc ID-Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 



Results: 



Success 
UnknownProcess 

Name Ambiguous 

If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
a single process, it suspends the process. If the process has a DebugPort set, it also send an M_DebugMsg 

yvt&cvnrto 1r\ 1%*n Anhitr* rxr^iri turfU QirtQiicr\jpvirf no /*i/? »«/?/fr/>w A/MMrp tV%a sl&nttft rysyrt if rat is\ /i^A*//yC f iO'W'T//lM/ii 1 
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PMDebug 

Invokes the debugger on a named (or numbered) process. 

Call: 

function PMDebug( 

ServPort : Port; 
ProcID : string) 
: GeneralReturn 



Parameters: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

Proc/JD-Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 



Results: 



Success 

UnknownProcess 

NameAmbiguous 
If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
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a single process, it suspends the process. If the process has a DebugPort set, it also send an MDebugMsg 
message to the debug port, with SigDebug as the reason. 
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PMKill 

kill a named (or numbered) process. 

Call: 

function PMKill( 

ServPort : Port; 
ProcID : string) 
: GeneralRetum 



Parameters: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcID-Na.m& of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 



Results: 



Success 
UnknownProcess 

NameAmbiguous 

If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
a single process, and the process does not have a DebugPort set, it terminates the process with reason= 
SigLevell Abort. If the process has a DebugPort set, it instead sends a MJDebugMsg message to the debug 
port, with SigLevell Abort as the reason (unless the debug port is set to DebugSignalOnly). 
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PMSetPriority 

Sets the priority of a named (or numbered) process, or of all of the processes in a process group. 

Call: 

function PMSetPriority( 
ServPort :Port; 
ProcID : string; 
priority : integer) 
: GeneralRetum 



Parameters: 



ServPort-Pon to Process Manager (exported by Pascallnit as PMPort). 

Proc/P-Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 
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Priority-Desired run priority for process: 
0: lowest priority 
15: highest priority 



Results: 



Success 

UnknownProcess 

NameAmbiguous 

BadPriority 
Changes the priority of the process or of all processes in the process group. 
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PMBroadcast 

Print a message in the Process Manager Window. This is used to display 'system ' messages. 
Call: 

function PM Broadcast 

CanrDni^ • Drtff* 
kJVl UUll ■lUllt 

s : string) 
: GeneralRetum 



Parameters: 



ServPort-Poit to Process Manager (exported by Pascallnit as PMPort). 
^-String to display. 



Results: 



success 



PMGetStatus 

Returns status for one or more processes. 

Call: 

function PMGetStatus( 
ServPort : Port; 
ProcID : string; 
var Stats : StatList; 
var Stats.Cnt : long) 
: GeneralRetum 

Parameters: 
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ServPort-Port to Process Manager (exported by Pascallnit as PMPort), 

ProcID-Can be: 

Process group name - 

returns status for all processes in group. 
Pattern to match (as in file name patterns) - 

returns status for all matching process names 
Process number for process - 

returns status for that process. 
Null String; 

returns status for all registered processes. 

■Sta/s-Returns a pointer to the array of status records, one for 
each process whose name matches ProcID. 

Stats C«*-Returns number of records in Stats 



Results: 



Success 

UnknownProcess-name didn't match any process 
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Asynchronous (Emergency) Messages 

Message sent to DebugPort to report an action on another process. (This is the same as the kernel's M 
DebugMsg.) 



Parameters: 



ATPor^-Kernel port of process affected. 
.4rg/-Always (present for historical reasons) 

/4rg2-Reason for DebugMessage: 

if the process was halted by an error, this is 
the GeneralReturn value describing the error 
(MemFault, UncaughtException, ...) 

if the process has a Process Manager Debug Port set 
(by PMSetDebugPort), and a signal was raised on 
process and not sent or ignored, this is the name 
of the signal that was raised. 



type DebugMessage = record 

Head : Msg; {Accent message header} 
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tKPort : TypeType; { (TypePT, 32) } 

KPort : Port { Kernel port of process affected } 

tArgl : TypeType; { (Typelnt32, 32) } 

Argl : Long { What happened, fi eld 1: always 0! } 

tArg2 : TypeType; { (Typelnt32, 32) } 
Arg2 : Long; { What happened, fi eld 2: 

GeneralReturn value for 

error or signal. } 
end; 
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Asynchronous (Emergency) Messages 

Message sent on process termination 



Parameters: 



Wait ID-Wait ID of process that died, as returned from PMGetWaitlD. 

Bpncnn—R t*ctQf\ri fr\r «ivyv»cc AaotVx' 

if killed by terminate (in Acclnt), 
PROCESSDEATH 

if killed by PMTerminate (in ProcMgr), 
the Reason given to PMTerminate. 

if the process re-registered with a different parent, 
ProcessDisowned. - . 

if the process was killed by a SigLevel[l,2,3] Abort, 
the signal value. 

LoadTime-CPU time to load process (microseconds) 

RunTime-CPU time to run process (microseconds) 

ElapseaTime-Total time elapsed from PMRegisterProcess until 
termination (60Hz clock ticks). 



const ProcessDeathMsgID= 3800; 

type ProcessDeathMsg = record 

Head : Msg; {Accent message header} 
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tWaitID :TypeType; { (typclnt32, 32) } 
WaitID : long; { Wait ID of process, 

returned from PMGetWaitID } 
tReason : TypeType; { (Typelnt32, 32) } 
Reason : long; { reason for process death } 

tLoadTime : TypeType; { (Typelnt32, 32) } 
LoadTime : long; { process Load time 
(microseconds) } 

tRunTime : TypeType; { (Typelnt32, 32) } 
RunTime- : long; { process Run time 
(microseconds) } 

tElapsedTime : TypeType; { (Typelnt32, 32) } 
ElapsedTime : long; { Elapsed time 
(ticks) } 
end; 
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Asynchronous (Emergency) Messages 

Message sent for signal to a process: this is sent to a process's SignalPort, or to its DATAPORT if the 
SignalPort has not been set or is NullPorU 



Parameters: 



Ctl Window-Window that the signal was sent from. If the signal was 
sent only to one process, it is the window that heads the 
control group for the process. 

S/graZ-signal sent to process. 



const SignalMsgID = 3801; 

type SignalMsg = record 

Head : Msg; {Accent message header} 

tCtlWindow : TypeType; { (TypePt, 32) } 
CtlWindow : window; { Window that signal was 

received on } 
tSignal : TypeType; { (Typelntl6, 16) } 
Signal : SignalName; { signal received } 
end; 
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7 Sesame: Interface to Prelimary Sesame File System 

Sesame provides routines to read, write and get information about files, given an absolute pathname for the 
file. The port to this server ( the ServPort parameter) is exported as SesPort from Pascallnit. See the section 
on Sesamoid in the Sesame: The Spice File System Manual for more information. 

7.1 Type Definitions 

The following definitions are from SesameUser.pas. 

const 

Path_Name_Size =255; { Number of characters in a Path_Name } 

Entry_Name_Size = 80; { Number of characters in an Entry_Name } 
type 

APath_Name = string[Path_Name_Size]; { An abs. pathname } 

Wild_APath_Name = string[Path_Name.Size]; { A wild abs. pathname } 

Entry.Name = string[Entry_Name_Size]; { A pathname component } 



{ Name.Flags: Flags giving desired treatment of names in Name Server calls. 
{ Note that specific flag values may be illegal for certain calls, and 
{ must be zero. 



const 
NFlag_Deleted = #000001; { Allow deleted names } 
NFlag_NoNormal = #000002; { Disallow normal (not deleted) names } 
.NFlagjtESERVED = #177774; { These bits reserved for expansion } 

type 
Name.Flags = .. #3; 



{ Name_Status: Flags useful for determining the disposition of a name in 
{ the name data base. 

const 
NStat.Deleted = # 000001 ; { Set if name is deleted } 
NStat.High = #000002; { Set if name is highest undeleted version } 
NStat_Low = #000004; { Set if name is lowest undeleted version} 
NStat.RESERVED = #177770; { These bits reserved for expansion } 

type 
Name.Status = .. #7; 



{ Entry.Type: The kinds of objects which can be in the name data base. 



27 Aug 84 



Scrvers-86 



const 

Entry.All =0; { Special value referencing all entry types } 

Entry.File =1; { Entry .Data is a File.ID } 

Entry.Directory = 2; { Name refers to another level of the 
name hierarchy. Entry .Data is empty. } 

Entry.Port =3; { Entry _Data is a port } 
type 

Entry.RESERVED = 4 .. #377; { These values reserved for expansion } 

Entry.UserDefined = #400 .. #77777; { Values available to the user } 
type 

Entry Type =0.. #77777; 



{ Entry_Data: The variant data record dependent upon the Entry.Type value. 

type 
Entry_Data = record case Entry.Type of 
Entry.File : ( {EDFilelD : File.ID - Not Yet Implemented} ); 
Entry.Directory : ( ); 
Entry>ort : ( EDPort : Port ); 
#400 : ( EDBytes : packed array [0..255] of bit8 ); 

#401 : ( EDWords : array [0..127] of integer ); 

#402 : ( EDLongs : array [0..63] of long ); 

#403 : ( EDString: string[255]); 

end; 

{ Entry.List.Record: ScanNames returns array of Entry.List.Record. 



itry.List.Record 


= record 


EntryName 


: Entry _Name; 


EntryVersion 


: long; 


Entry Type ; 


Entry.Type; 


NameStatus 


: Name.Status; 


end; 





Entry.ListArray = array [0..0] of Entry.List.Record; { hack } 
Entry.List = t Entry JListArray; 



{ Valid.Name.Chars: Those 7-bit ascii characters which can occur in an 
{ entry name without being quoted. Note that to match uppercase, 
{ uppercase letters also have to be quoted. 

const 
Valid Name Chars = { Put in a string since can't put in a set } 
'$-."+0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ.abcdefghijklmnopqrstuvwxyz'; 
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{ Separator characters for parts of Path_Name syntax. 

const 

Dir_Separator = V; { Directory separator } 

Ver_Separator = '#'; { Version number separator } 

Quote_Char = 'V; { Quote character for "runny" characters } 

Up_onc_Directory = '../'; 
This_Directory = './'; 

{ Group.ID: An identifier for a User Group 

type 
Group_ID = long; 



{ File.Data: A pointer to a file mapped into memory 



type 
MlejData = pointer; { A pointer to data for file calls } 



{ PrintName: A short string name in the file header. 



const 

PrintName_Size = 80; { Number of characters in a file PrintName } 
type 

PrintName = string[PrintName_Size]; { A print name string } 



DataFormat: A user-defined longword for storing data format information. 
System- defined values are given below. User-defined values must 
have a non-zero high word (#200000 or greater). These values are 
intended to be used by programs which need to know about data formats 
in order to convert from one format to another (such as FTP). 



{ Unspecified data format } . 

{ 8 bit binary data } 
{ 16 bit binary data } 
{ 32 bit binary data } 
{ 36 bit binary data } 



DFormJJnspecified 


= 0; 


DForm_8_Bit 


= 


8; 


DForm[l6_Bit 


= 


16; 


DForm_32.Bit 


= 


32; 


DForm 36 Bit 


= 


36; 



27 Aug 84 



Servers-? 



DForm.CRLFText = #413; { CRLF delimited text } 

DForm^LFText =#410; { LF delimited text } 

DForm_Press = # 1000; { Press file format data } 
type 
Data.Format = long; 



{ File_Header: How the user perceives the file header information. It is 
{ actually generated by the GetFileHeader style calls from the real 
{ header. 



type 
File_Header = packed record 
FileSize : long; { Size of file in bytes } 
DataFormat : long; { Advisory data format } 
PrintName : Print_Name; { The file print name } 
Author : Group _ID; { Who wrote the file } 
CreationDate : Internal_Time;{ When it was written } 
AccessID : Group.ID; { Who last accessed the file } 
AccessDate : Internal,Time;{ When it was last accessed } 
FHdr.RESERVED : array [56..64J of integer; { Pad for expansion } 
end; 

{ Error return values 

const 
Sesame.Error.Base = 1200; 

NameNotFound = Sesame.Error.Base + 1; 
DirectoryNotFound = Sesame.Error.Base + 2; 
DirectoryNotEmpty = Sesame.Error.Base + 3; 
BadName = Sesame.Error.Base + 4; 

InvalidVersion = Sesame.Error.Base + 5; 
InvalidDirectoryVersion 

= Sesame.Error.Base + 6; 
BadWildName = Sesame.Error.Base + 7; 
NotAFile = Sesame.Error.Base + 8; 

NoAccess = Sesame.Error.Base + 9; 

NotSamePartition = Sesame.Error.Base + 10; 
ImproperEntryType = Sesame.Error.Base + 11; 
NotADirectory = Sesame.Error.Base + 12; 

7.2 Procedures and Functions 

The following procedures and functions are found in SesameUser.pas. 
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Several of the calls are provided with two or more forms, with one being a subset of the other. Where this is 
the case, the subset form will have a name prefix of Sub, whereas the full form of the call will have a name 
prefix of Ses. 

■ I M fl BIHI MIBIMIBmiMIM I B I «IBI M IMIWIMI W I«l« I HIM I «IWIW I WIWIM I W I « I M»BIBIMI MI ■ 

InitSesame 

Initialize the local copy of this module. 
Call: 

procedure InitSesame(RPort : port); 

1IB I BI B IM I BIiai Ba iMIBlBiniMI« I BIM i a i Bmi Mi «lMIM I iniai M l « liai«iniBIMI« I HlMiia i B I I ■ 

SubReadFile 

Simplest way to read a file. 

Call: 

Function SubReadFile( 

ServPort : port; 
APathName : APath_Name; 
var Data : File_Data; 
var Data.Cnt : long) 
: GeneralRetura 

Parameters: 

ServPort-port to the Name Server 

apathname-the absolute pathname to read the data from 

data pointer-a pointer to the data read in memory 

DataCnt-thz total number of bytes read 
Results: 

success-thQ data was successfully mapped into memory 

no such name-no entry was found under apathname 

access vioIation-Jhe requesting client tried to read a file 
for which he did not possess rights 

not afile-the entry found under apathname was not a file 

no such file 7Z>-the file associated with the entered 
ID could not be found 

The SubReadFile request is used to map the data associated with the given filename into memory. Note that we 
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map the entire file in, thus there are no arguments specifying the size or position of the data to be read. We can 
get away with mapping the whole file since we actually will only bring in the pages which are touched, the rest 
being backed to secondary storage. Holes in the file will be mapped in as valid zero pages which will actually be 
created if written to. 

■ I ^ IMIBIBI M IDi m iMIBini Bl lll BIMf l « IBIBIBI B I B IBI B IBIMIBIBi|MI M| M |p in i B I| M | M | 



SesReadFile 



Read a file with complete specification 
Call: 



Parameters: 



Results: 



Function SesReadFile( 

ServPort : port; 
var APathName : APath.Name; 
var Data : File .Data; 
var Data_Cnt : long; 
var DataFormat : Data .Format; 
var CrcationDate: Internal .Time; 
var NamcStatus : Name .Status) 
: GeneralReturn 



ServPort-port to the Name Server 

apathname-\he absolute pathname to read the data from 

Data-a. pointer to the data read in memory 

Data, Cnt-the total number of bytes read 

DataFormaHme of {unspecified, text, bit8, bitl6, bit32, bit36, press, ...} 

CreationDate-\he date and time the file was written 

NameSlatus-low version, high version 

success-the data was successfully mapped into memory 

no such name-no entry was found under apathname 

access violation-the requesting client tried to read a file 
for which he did not possess rights 

not afile-the entry found under apathname was not a file 

no such file ID-the file associated with the entered 
ID could not be found 
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The SesReadFile request is a long form of the SubReadFile call. It returns several parameter values which the 
short form does not. 

SubWriteFile 

Simplest way to write a file 
Call: 

Function SubWriteFile( 

ServPort : port; 
var APathName : APath.Name; 
Data : File_Data; 
Data.Cnt : long; 
DataFormat : Data .Format; 
var CreationDate: Internal _Time) 
: GeneralReturn 

Parameters: 

ServPort-port to the Name Server 

Apathname-the absolute pathname to write the data to 

Data-a pointer to the data in memory 

DataCnt-the number of bytes to be written 

DateFormat-one of {unspecified, text, bit8, bitl6, bit32, bit36, press, ...} 

CreationDate-thQ date and time the file was written 
Results: 

success-the data was written under the name returned 

access violation-the requesting client tried to write a file for which he did not possess 
rights 

conflicting version-tiie explicit version number was less than or equal to that of an 
existing version 

allignment error-the data was not on a page boundry 
The SubWriteFile request is used to enter a new name into the directory structure and write a file under that 
name. This short form of the call picks up defaults for unspecified parameters from previous versions or 
directory defaults. The user must have CreateNames rights in the directory or Supercede rights on the previous 
version. Empty pages need no disk pages assigned to them. 
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SesGetFileHeader 



Get file header information 
Call: 



Parameters: 



Results: 



Function SesGetFileHeader( 

ServPort : port; 
APathName : APath Name; 
var FilcHeader : File_Header) 
: GeneralReturn 



ServPort-port to the Name Server 

Apalhname-the absolute pathname with which to find the file 

FileHeader-a data structure containing the 
fields of the file header. 

success-thc header data was successfully returned 

no such name-no entry was found under apathname 

access violation-the requesting client tried to read a file header 
for which he did not possess rights 

not afile-the entry found under apathname was not a file 

no such file ID-the file associated with the entered ID 
could not be found 



The SesGetFileHeader request is used to return fields from the file header. 
■i Mi«i m M mm iBi mmm M mi Mi mM i M i im iM miB iMiain i M 

SesReadBoth 

Read the contents and file header information of a file 
Call: 

Function SesReadBoth( 

ServPort : port; 
var APathName : APath _Name; 
var Data : File .Data; 
var Data.Cnt : long; 
var FileHeader : File .Header; 
var NameStatus : Name .Status) 
: GeneralReturn 

Parameters: 



lai m aii 



mam 
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ServPort-port to the Name Server 

Apathname-the absolute pathname with which to find the file 

Data-a pointer to the data read in memory 

DateCnt-ihe total number of bytes read 

FileHeader-a data structure containing the 
fields of the file header. 

NameStatus-deleted/undcleted, low version, high version 

success-the header data was successfully returned 

"no such name"-no entry was found under apathname 

"access violation"-thQ requesting client tried to read a file 
header for which he did not possess rights 

"not aJHe"-\hQ entry found under apathname was not a file 

"no such file ID"-the file associated with the entered ID 
could not be found 

The SesReadBoth request is used to return both the data from a file and fields from its header. 
miiniMPBiniiniiiiM i MiMirniEii ■! ■! ■ ! ■in i ■"■—»—"-■■■"«"■»'»■»■■■■"■■"■'■■'■'■ ■■ |n|n|1 

SubLookUpName 

Lookup a file ID 
Call: 

Function SubLookUpName( 
ServPort : port; 
var APathName : APath.Name; 
var EntryType : Entry .Type; 
var Entry Data : Entry .Data; 
var NameStatus : Name .Status) 
: GeneralReturn 



H— a 



Parameters: 



ServPort-pon to the Name Server 

Apathname-ihe name to be looked up (may not 
contain wildcard characters) 

EntryType-lhe type value of the entry found. Some example 
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values are File, Directory, and Port. 

EntryData-a variant field dependent upon the entry type. 

A File ID will be returned here for a File entry, whereas there 
will be no data returned for a Directory- all 
that this call will tell you about a directory 
is that it exists. 

AfameSVa/Ms-deletcd/undeleted, low version, high version 

success-ttiQ name was successfully looked up. 

name not found-thc specified name was not found 

access violation-\he client does not have sufficient rights to 
look up the given name 

This function provides a simple way to look up a name. If any entry encountered during the parsing of 
apathname is of type Symbolic Link, a macro expansion is performed using the value of that entry in place of 
the corresponding name in apathname. If the final result is of type FID or IPC Port, the corresponding FID or 
IPC port is returned If it is of type Directory no entry data is returned, but entry type specifies the fact that a 
lookup on a directory name was done. If apathname does not contain a version number, the most recent version 
is assumed 

■ IMI ^ I« I MIMI«IMIWIM IMI B m iMiniWIBI M I«IMI HI MI 1I B I MIMIM IBI BIBIMiniB i lB I HI B I«l ■ 

SubTestName 

See if a file exists 

Call: 

Function SubTestName( 

ServPort: port; 
var APathName : APath.Name; 
varEntryType : Entry .Type; 
var NameStatus : Name .Status) 
: GeneralRetum 



Parameters: 



ServPort-port to the Name Server 

Apathname-the name to be looked up (may not 
contain wildcard characters) 

EntryType-the type value of the entry found. Some example 
values are File, Directory, and Port. 

NameStatus-deteted/undeleted, low version, high version 
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Results: 



success-ihe name was successfully found 

name notfound-\he specified name was not found 



access violalion-\he client does not have UseNames rights 
on the name's directory 

SubTestName is like SubLookupName except that it never returns the entry data associated with a name, but 
only the entry type. Note that this only requires UseNames rights on the parent directory, whereas 
SubLookupName requires Lookup rights on the name itself- a much stronger requirement. It is anticipated 
that this call will be used when all that is desired is to test for the existance of a name, and to determine its 
type. 



■ ■ i— ■ — 1 ■ 



SubEnterName 



Enter a file or port name in a directory 
Call: 



Parameters: 



Results: 



Function SubEnterName( 

ServPort : port; 
var APathName : APath.Name; 
EntryType : Entry .Type; 
Entry Data : Entry .Data) 
: GeneralReturn 



ServPort-port to the Name Server 

Apathname-the name to be entered into the directory structure 

EntryType-the type value of the object to be entered. Some 
example values are File, Directory, and Port. 

EntryData-a. variant field dependent upon the entry type. 

For instance, this field must contain a File ID for type File, and 
an IPC port for type Port. For type Directory, this field 
is left empty, seeing as how the user can't write any directory data 
directly. Use of this call with entry type Directory enters a 
new directory, thus no special call is needed for that purpose. 



success-apathnamewas successfully entered 
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conflicting version-thc version number specified in 

apathname was less than or equal to that of an already existing 
version 

access violation-thc client does not possess CreateNames 
rights in the specified directory 

invalid directory version-only one version number of a 
directory is allowed 

The SubEnterName request is used to place a name and entry value pair in the directory structure. It requires 
CreateNames permission in the directory within which the name is being entered if no version of the name 
already exists else if a version of the name already exists, then Supersede privileges on the name are needed If 
a previous version of the name already exists in the directory and no version number is specified in apathname, 
the name is entered with the next higher version number. If a previous version of the name already exists and a 
version number is specified in the name, then it must be greater than the highest version number so far. If no 
previous version of the name has ever existed, then version one is assigned if none is specified in apathname, 
otherwise the specified version is used 

■ ■■illl i B II I M I III I M IMI III IIMIW II IIIM IM II II I^IMI II M I MI M I WH IMI M I M IM III M IIIBi l 
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SubDeleteName 



remove a name from a directory 
Call: 



Parameters: 



Function SubDeleteName( 

ServPort : port; 
APathName : APath_Name) 
: GeneralReturn 



ServPort-thQ name to be deleted 



Results: 



Apathname 

success-the name was successfully deleted 

nonexistent name-the name specified does not exist 

access violation-the user does not possess DeleteNames 
rights on the name specified 

name already deleted-the given name was already deleted 

directory not emp/y-illegal to delete a non-empty directory 
The SubDeleteName request is used to delete a name from a directory. It requires DeleteNames permission in 



21 Aug 84 



Servers-97 



the directory or Delete permission on the name. The name is marked as deleted, but remains in the directory 
and is queued for expunging by the Migration Server. If no version number is specified then the lowest version 
in the directory will be deleted. 
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SubReName 

rename a file or port 

Call: 

Function SubReName( 

ServPort : port; 

OldAPathName : APath_Name; 
var NewAPathName : APath .Name) 
: GeneralRetum 



Parameters: 



Results: 



ServPort-port to the Name Server 

OldAPathName-absdlutQ pathname of the object to be renamed 

NewAPathName-new name to enter the object under 

success-the name was successfully changed 



access violation-the client either does not have the proper rights 
to delete oldapathname or to enter new apathname 

SubRename enters the object specified by old apathname into into the global name space as new apathname 
and then removes the old apathname. The access control list of the object is moved with it. 
m \ m \m \ m \m\ m \ m \ m \ m\ wk\u \m \ m\m \ m \n\m\ m \ m \m\m\ wk\ m\ m \ m \m \ t&\wi\ m \m\m\m\m\v * \wz\ m\vik \ ■ 

SesScanNames 

Returns a list of names in a directory 

Call: 

Function SesScanNames( 

ServPort :port; 

WildAPathName : Wild APath Name; 
NameFlags : Name .Flags; 
EntryType : Entry .Type; 
var DirectoryName : APath .Name; 
var Entry List : Entry .List; 
var EntryList.Cnt : long) 
: GeneralRetum 

Parameters: 
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ServPori-Jho. absolute pathname to be scanned 

(may contain wildcard characters in the terminal component) 

WildAPathName 

NawieF/ags-inhibit/allow deleted/undeleted names 

EnlryType-\he entry type being scanned for. The special type 
designator All may be given, in which case names of all entry 
types are returned. 

DirectoryName-the absolute pathname of the directory in which 
matches occured 

EntryList-the sorted entry names, types, version numbers 
and name status flags 

of all names matching wild apaihname in the first element of 
search list where a match occured 

EntryList_Cnt-\hQ actual number of list elements 
returned. Will be zero if no match occured. 

success-the given wild absolute pathname was successfully scanned 

access violatiorHhQ client does not possess 
ReadNames rights on the directory to be scanned 

illegal pathname- wildcards were found in 

wild apaihname at other than the terminal component 

The SesScanNames call is used to search for a given pattern in a specified directory. It will sort and return all 
the matches to the given pattern in the directory. Optionally, names only of a specific entry type can be scanned 
for. Symbolic links are not expanded, and are returned by this call. Depending on the value of name flags, only 
active names, deleted names or both are considered If no version number is specified, then the highest existing 
version of the name is returned If the version number is wildcarded, then all existing versions of the name are 
returned The version field for directory and symbolic link entries will be returned as zero. Note that 
wildcarding is permitted only in the terminal component of wild apaihname. This call requires either 
ReadNames access on the directory being scanned, in which case all matches will be returned, or else Visible 
access on each match which is to be returned 



Results: 
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8 TimeServer 

8.1 Introduction 

The Time Server provides all of the time facilities for Accent. It can return the time in a number of different 
formats. 

Internally, time is kept as the number of milliseconds since midnight, November 17,1858 Greenwich Mean 
Time (the Smithsonian time standard). In order to store the time efficiently, it is kept as an ordered pair, the 
first component representing the number of weeks that have passed since the base date-time and the second 
component representing the number of milliseconds that have passed in that week. This format also allows 
efficient comparison of times. Conversions to local time are done using a time zone index and information 
regarding whether or not to apply daylight savings time. 

The zone record, Zonejnfo, allows you to specify and receive zone information. Both the zone number and 
application of daylight savings time may be either specified explicitly or defaulted, depending on the 
settings of the UseTimeZone and UseDaylight bits. The zone record is used in UserTime. 

The date and time information in User_Time is broken down into fields for input and output. Both the time 
zone index and application of daylight savings time can be either explicitly specified or defaulted through 
use of the Zone.Info fields. The Weekday field is unused for input 

8.2 Definitions 

The following definitions are from TimeDefs.pas. 

InternalTime: a record containing the date and time in Greenwich 
Mean Time. This is the Smithsonian Institute's time standard. 
To optimize space usage, we store 
time as an ordered pair, the first representing the number of 
weeks which have passed since 17-Nov-1858, when the 
Smithsonian time standard began. The second represents the 
number of milliseconds which have passed in that week. 

type 
Internal_Time = record 
Weeks : integer; {Number of weeks since 17-Nov- 1858} 
MSecInWeek : long; { Number of milliseconds in that week } 
end; 



Date.Fields: fields necessary for representing date information 
without respect to the time. Used in by User_Time. 

type 
Date_Fields = packed record 
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Year : integer; { Such as 1982 } 

Month : 1 .. 12; { 1 = January, 12 = December } 

Day : 1 .. 31; 

Weekday : .. 6; { = Monday, 6 = Sunday (output only) } 

end; 



Time_Ficlds: fields necessary for representing time information 
without respect to the date. Used in UscrTime. 

type 
Time.Fields = packed record 
Hour : .. 24; 
Minute : .. 59; 
Second : .. 59; 
Millisecond : .. 999; 
end; 



Zone.Info: this record allows the user to specify and receive time 
zone information. Both the zone number and application of 
daylight savings time may be either specified explicitly, or 
defaulted, depending upon the settings of the UseTimeZone and 
UseDaylight bits. Used in UserTime. 

type 
Zone_Info = packed record 
TimeZone : integer; { Increasing minutes west from GMT. 

GMT = 0, EST = 5*60, CST = 6*60, ... 

Used only if UseTimeZone is set } 
UseTimeZone : boolean; { True when TimeZone field is valid, 

else false when local time zone is 

to be used. } 
Daylight : boolean; { True if daylight savings time is to 

be applied. Used only if 

UseDaylight is set } 
UseDaylight : boolean; { True if Daylight savings field is 

valid, else false when the system 

default for daylight savings time 

application is to be used. } 
end; 



UscrTime: Date and Time informatien broken down into fields as the 
user would want to use it for input and output Both the time 
zone index and application of daylight savings time can be 
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either explicitly specified, or defaulted through use of the 
Zonelnfo fields. The Weekday field is unused for input 



type 




User.Time 


= packed record 


Date 


: Date_Ficlds; 


Time 


: Time.Fields; 


Zone 


: Zone_Info; 


end; 





The following flag values may be ORed together to form TimeFormat values. 



const 
TF_Weekday = # 000001; { If set output the day of the week 

according to the setting of 

TFFullWeekday else don't output 

the day of the week } 
TF FullWeekday = #000002; { If set output full text for the 

weekday else the 3- letter 

ahhroiMati/yn f\A ' rxnAoy /\Jff\r\\ \ 

TF.NoDate = # 000004; { If set do not output date and ignore 

fl ags through TF.NoTime } 
TF.FullMonth = #000010; { If set output full text for the 

month when the month is alphabetic 

else the 3- letter abbreviation . 

(March/Mar) } 
TFJullYear = # 000020; { If set output the year as a 4-digit 

number else the year is is output as 

a 2- digit number if in the range 

1900-1999(1982/82)} 

{ The next six settings are mutually exclusive } 

TF Dashes = #000000; { Output date as day-month-year 

(22-Mar-60)} 
TF Spaces = #000040; { Output date as day month year 

(22 Mar 60)} 
TF Reversed = #000100; { Output date as month day, year 

(Mar 22, 60)} 
TF Slashes = #000140; { Output date as month/day/year 

(03/22/60)} 
{ #000200 is reserved for future expansion} 
{ #000240 is reserved for future expansion} 
TF ANSI = # 000300; { Output date according co AN5TX3.30-1971. 

Also slightly affects time formatting. 
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(600322)} 
TF.ANSI.Ordinal = #000340; { Similar to TF ANSI but 3-digit day of-year 

instead of month and day. 

(60082)} 
TF_DateFormat =#000340; { A mask allowing us to examine the above. } 

TF_NoTime = #000400; { If set do not output time and ignore 
fl ags through TF.NoColumns } 

{ The next two settings are mutually exclusive } 

TF_NoSeconds =#001000; { If set do not output the seconds} 
TF.Milliseconds = #002000; { If set output milliseconds as 

hh:mm:ss.sss else omit them 

(17:00:00.001/17:00:00) } 

TF_12_Hour = # 004000; { If set output the time in 12-hour 
format with 'am' or 'pm' following the 
time else output in 24- hour format 
Note that exact NOON outputs neither 'am' 
nor 'pm' because 12:00am is 0000 and 12:00pm 
is 2400. Use of TF_12_Hour with TF ANSI or 
TF.ANSI.Ordinal is supported but not 
recommended for a number of reasons. If used 
with either ANSI format, however, the codes 
'A', 'P\ and 'N' are used for am, pm, and 
noon, respectively. 
(5:00:00pm/17:00:00)} 

TF.TimeZone = #010000; { If set output the time zone as -zzz 
after the time else omit it 
(17:00:00- EDT/17:00:00) } 

TF_NoColumns = #040000; {If set output numeric date/time 

quantities in the smallest fi elds 

into which they will fi t, else 

output them in fi xed size fields. If 

not set, the date/time will be 

output in fi xed length fields, thus 

making this format appropriate for 

columnar display. Note that TF.FullMonth 

and TF .Full Weekday are currently NOT padded 

with blanks, even if TF.NoColumns is off". } 
TF.BlankPad = #020000; { If set, pad fixed- width numbers with blanks 

instead of zeroes WHERE REASONABLE. Ignored 

if TF.NoColumns is set. } 

TF Never = # 100000; { If set allow the distinguished time 
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value NEVER to be output as the 
string 'Never' else signal an 
error} 

The following flags arc returned to indicate which fields of the 
date and time were present upon parsing a date/time string. 



const 
TP Weekday = #000001; { Weekday present } 
TPDate = #000002; { Date present} 
TPTime = #000004; { Time present } 
TP^Zone = #000010; { TimeZone present } 
TPNever = #000020; { Time input was NEVER } 
TP'RESER VED = # 177740; { Reserved for expansion } 



String.255: The maximum length string. We parse dates from such strings. 
This definition should probably be somewhere else. 

type 
String.255 = string[255]; 

83 Exceptions 

BadDateTime This exception is raised if a bad date/time value is 

passed to any of the TimeServer routines, or if the TimeFormat 
flags (for conversion to String format) are invalid. 

TimeNotlnitialized This exception is raised if the system date, time, 
and time zone have not been set 

8.4 Procedures 

The following procedures are from TimeUser.pas. 

rminimoociiDiMiwiiin i iiginiisimM'^'™'" , ~"^ , ~ , ~^ g a 

SetDateTime 

Sets current date and time. 
Call: 

Procedure SetDateTime( ServPort : port; 
ITime : Internal Time) 

Parameters: 

ServPort-TwiePort (service port to Time Server) 
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/7/we-Internal_Time record for time to set 
Returns: 

Raises TimeNotlnitialized if system time zone and daylight switch have 
not been set 
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SetSystemZone 

Sets the system defaults for time zone and whether to use Daylight time. 
Call: 

Procedure SctSystemZonc( ServPort : port; 
TimeZone : integer; 
DSTWhenTimely : boolean) 

Parameters: 

ServPorl-TimcPort (service port to Time Server) 

TimeZone-System time zone to set (refer to the constant definitions). 

DSTWhenTimely-WhetheT to use daylight time during the USA daylight 
time interval. 
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GetDateTime 

Gets current time, in Internal Time format. 
Call: 

function GetDateTime (ServPort : Port) 
: Internal_Time 

Parameters: 

ServPort-TimePort (service port to TimeServer) 
Returns: 

Raises TimeNotlnitialized if system time has not been set 

GetUserTime 

Gets current time, in User Time format, according to system time zone and daylight time defaults. 
Call: 
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Parameters: 



Returns: 
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function GetUserTime ( ServPort : Port) 
: User Time 



ServPort-TimcPort (service port to Time Server) 



Raises TimeNotlnitialized if system time has not been set 
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function GetStringTime( ServPort : Port; 
TimeFormat : integer) 
: String 

Gets current time, in string format. 
Call: 

GetStringTime 

Parameters: 

ServPort-TimePort (service port to Time Server) 



Returns: 



77meFomta/-Format for the string (refer to the constant definitions) 
Raises TimeNotlnitialized if system time has not been set 
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T IntToZone 



Converts internal time to user time, according to supplied time zone. 

Call: 

function T.IntToZone ( ServPort : port; 
ITime : Internal _Time; 
WantZone : Zonejnfo) 
: User Time 



Parameters: 



Returns: 



ServPorf-TimePort (service port to Time Server) 

777ffie-Internal_Time record 

WantZone-ZoneJnfo record containing Zone and daylight desired. 

User Time record representing ITime. 
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TIntToUser 

Converts internal time to user time, according to supplied time zone and daylight time defaults. 
Call: 

function TJntToUser ( ServPort : port; 
ITime : Internal .Time) 
: User Time 



Parameters: 



Returns: 



ServPort-TimePort (service port to Time Server) 
/r/me-Internal.Time record 

User Time record representing ITime. 



TUserToInt 

Converts user time value to internal time. 
Call: 

function TUserToInt ( ServPort : port; 
UTime : User .Time) 
: Internal Time 



Parameters: 



Returns: 



Sen^Porf-TimePort (service port to Time Server) 
L77me-User_Time record 

InternalTime corresponding to UTime, 
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T UserToString 

Converts a user time record to a string representing the time, according to the conversion parameters. 
Call: 

function T.UserToString ( ServPort : port; 
UTime : User .Time 
TimeFormat: integer) 
: String 



27 Aug 84 



Servers-107 



Parameters: 



Returns: 



ServPort-TimoPovi (service port to Time Server) 

UTime-UserTime record 

TimeFormat-Format desired for the output (refer to the constant 
definitions) 

A string representation ofUTime. 
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TIntToString 

Converts an internal time record to a string representing the time, according to the conversion parameters. 
The system defaults for time zone and daylight time are used. 

Call: 

function TIntToString ( ServPort : port: 
ITime : Internal .Time 
TimeFormat: Integer) 
: String 



Parameters: 



Returns: 



ServiVf-TimePort (service port to Time Server) 

/r/me-Interaal Time record 

TimeFormat-Format desired for the output (refer to the 
constant definitions.) 

A string representation of ITime. 



T StringToUser 

Converts a siring to a user-time record 
Call: 



function T StringToUser( ServPort : port; 
STime : String .255; 
var Index : integer; 
vafWhatlFound: integer) 
: User Time 
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Parameters: 



Returns: 



ServPort-TimcPort (service port to Time Server) 

ST/me-String to be converted to time. 

Index-Position in string to start scanning for time. Returns the first 
character past the end of the valid time string. 

WhatI Found-Returns what was parsed from the time string . 
Raises BadDateTime ifSTime malformed. 



TStringToInt 

Converts a string to an internal-time record 

Call: 

function TStringToInt ( ServPort : port; 
STime : String .255; 
var Index : integer; 
var WhatlFound: integer) 
: Internal Time 
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Parameters: 



Returns: 



ServPort-TimoPort (service port to Time Server) 

STime-Stiing to be converted to time. 

//^ex-Position in string to start scanning for time. Returns the first 
character past the end of the valid time string. 

WhatI Found-Returns what was parsed from the time string 
Raises BadDateTime if STime malformed 
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TNever 

Returns the internal time value representing "never". 

Call: 

function TNever ( ServPort : Port) 
: Internal Time 
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Parameters: 

ServPort-TimePori (service port to Time Server) 
Returns: 

IntemalTime record representing Never. 

8.5 Valid Time Zones 

The valid time zones accepted by T.StringToUser and TStringToInt are, 

GMT Greenwich MeanTime 

UT UniversalTime (Same as GMT) 

NST Newfoundland Standard Time (-3:30) 

AST Atlantic Standard Time (-4 hours) 

ADT Atlantic Daylight Time 

EST Eastern Standard Time (-5 hours) 

EDT Eastern Daylight Time 

CST Central Standard Time (-6 hours) 

CDT Central Daylight Time 

MST Mountain Standard Time (-7 hours) 

MDT Mountain Daylight Time 

PST Pacific Standard Time (-8 hours) 

PDT Pacific Daylight Time 

YST Yukon Standard Time (-9 hours) 

YDT Yukon Daylight Time 

HST Hawaii- Alaska Standard Time (-10 hours) 

HDT Hawaii- Alaska Daylight Time 

BST Bering Standard Time (-11 hours) 

BDT Bering Daylight Time 
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9 The Typescript Manager 

9.1 Introduction 

The Typescript manager maintains standard text windows (Typescripts), providing line editing and 
redisplay functions for user programs that do not require graphics output or elaborate input control. 

Typescript remembers the last several pages (a window's worth) of text output by the program using a 
typescript. When a text window changes state, size, or coveredness, Typescript will also redisplay 
information that may have scrolled from the window. 

Typescript allows the user to edit input lines using a subset of the commands available in the system editor. 
The user can use all of the editor's single- line editing functions, and recall previous input lines to be edited 
into new input lines. 

Typescript also handles Escape Completion for each typescript The user may type a partial filename and 
press the Escape key; Typescript will ask the file system to complete the file name by finding the longest 
unambiguous match to the partial name. It will then add the name to the line of input, so that the user can 
specify the rest of the name or add more to the line. 

Typescript can either stop at the end of each screenful of output ('more' mode) or scroll output 
continuously. The user can select which mode to use, under keyboard control. 

In 'More' mode, when a full page of output has been displayed, a black bar appears at the bottom of the 
window. The user then presses LineFeed to display the next page of output 

In continuous scroll mode, the user can use the Process Control Functions Suspend and Resume to stop or 
start output 

9.2 Use 

Each typescript maintained by the Typescript manager has its own port. All requests for input output and 
control of a typescript are directed to its port. There is a master typescript port used to create new 
typescripts. 

When a user program is started, the mater typescript port is TypescriptPort and the port associated with the 
program's window is UserTypescript Both of these are in PascallnitPas. Pascal input and output through 
the default files INPUT and OUTPUT is directed to UserTypescript (unless input or output has been 
redirected). 

A program may create a new Typescript in an existing window by using the call STSOpen Window and 
providing it with the window to use. It returns a port for the typescript in that window. 

The program may then request a full line of input with STSGetString. This will allow the user to type a line 
of input using all of the line editing commands. When the user types RETURN, the line is finished and is 
returned to the program. 

A program may ouput a line of text by calling STSPutString, supplying the typescript and the string to 
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output. Each LineFeed chatacter in the string ends a line of text, scrolling the typescript and putting the 

ntext character at the start of the next line. The string does not need to end with a line feed. 

A program can ask the Tyepscript Manager to stop refreshing the screen. The call STSGrabWindow returns 

the window associated with the supplied typescript When the program is terminated, the Typcsscript 

Manager will resume control over the window and refresh it, erasing whatever the program had displayed 

on it 

Since each Typescrip may be used by a program or shell that has its own environment, a program can 

specify the environment connection to be used by the typescript This controls the list of files scanned for 

Escape Completion. Each Typescript has its own Environment Connection. 

9.3 Definitions 

The following definitions are from TSDefkpas. 
type 

Typescript = Port; 
TString255 = String[255]; 

TSCharArray = packed array[0 .. 1] of Char; 
pTSCharArray = t TSCharArray; 

9.4 Routines 

The following routines are from TSUser.pas. 

STSOpen 

Creates a Typescript inside a viewport The typescript uses the system font, displays long lines by wrapping 
around, and stores three windows' worth of output 

Call: 

Function STSOpen( 

ServPort: Port; 
vp : viewport; 
env: Port) 
: Typescript 



Parameters: 



ServPort-The master Typescript service port (TypescriptPort) 

vp-The viewport to contain the typescript 

env- An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 
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Returns: 

A port for a new typescript. 

STSOpenWindow 

Creates a Typescript inside a window. The typescript uses the system font, displays long lines by wrapping 
around, and stores three windows' worth of output. 

Call: 

Function STSOpen( 

ServPort: Port; 
w : window; 
env: Port) 
: Typescript 



Parameters: 



Returns: 



ServPort-The master Typescript service port (TypescriptPort) 

w-The window to contain the typescript 

env-An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 

A port for a new typescript 
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STSFuIlOpen 

Creates a Typescript inside a viewport, allowing the program to select more parameters for the typescript 

Call: 

Function STSFullOpen( 

ServPort: Port; 
vp : viewport; 
env: Port; 
fontName: TString255; 
doWrap : Boolean; 
dispPages : Integer) 
: Typescript 



Parameters: 



ServPort-The master Typescript service port (TypescriptPort) 
yp-The viewport to contain the typescript. 
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Returns: 



env-An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 

fontName-The name of the font containing the font to use for the 
typescript It must be an absolute path name. 

do Wrap-if TRUE, displays lines wider than the window by wrapping 
to the start of the next line. If FALSE, truncates long lines at the right 
margin of the window. 



A port for a new typescript. 



STSFuIIOpenWindow 

Creates a Typescript inside a window, allowing the program to select more parameters for the typescript. 
Call: 

Function STSFullOpen( 

Vl!iUU! run, 

w : Window; 
env: Port; 
fontName : TString255; 
doWrap : Boolean; 
dispPages : Integer) 
: Typescript 



Parameters: 



Returns: 



ServPort-The master Typescript service port (TypescriptPort) 

w-The window to contain the typescript 

env-An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 

fontName-The name of the font containing the font to use for the 
typescript It must be an absolute path name. 

do Wrap-if TRUE, displays lines wider than the window by wrapping 
to the start of the next line. If FALSE, truncates long lines at the right 
margin of the window. 

A port for a new typescript 
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STSGetChar 

Returns a singel character of input from a typescript. If a full line has not been typed, it invokes the line editor 
and waits until a line is completed If a line has been typed, it removes the next character from the start of the 
line and returns it 
Call: 

Function STSGetChar( 

ServPort: Typescript) 
: Char 

Parameters: 

ServPort-Port for the typescript 
Returns: 

The first character on the input line. 
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STSGetString 

Returns an entire line of input from a typescript. If a full line has not been typed, it invokes the line editor and 
waits until a line is completed It then returns the entire line. 

Call: 

function STSGetString( 

ServPort : Typescript) 
: TString255 

Parameters: 

ServPort-Poit for the typescript 
Returns: 

The entire input line. 
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STSPutChar 

Writes a single character to a typescript. 
Call: 

Procedure STSPutChar( 

ServPort : Typescript; 
ch : Char) 

Parameters: 
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ServPort-The port for the typescript 

ch-The single character to output 
A LineFeed character ends the current output line. A BELL character (control G) flashes the viewport 
containing the typescript. Any other character is appended to the current line, possibly translated: 

Control character (chr(0)..chr(13)) are displayed as tChar. 

DEL is displayed ast{. 

Printing characters (space through '} ') are displayed as 
themselves. 

Any character greater than chr(127) is displayed as the corresponding character in the font for the typescript, 
minus 128. This allows character in the font with numeric values less than 32 to be displayed as normal 
printing characters. 
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STSPutString 

Writes a string of characters to a typescript. Each character in the string is displayed according to the 
description for STSPutChar. 

Gail: 

Procedure STSPutString( 

ServPort : Typescript; 
s : TString255) 

Parameters: 

ServPort-The port for the typescript 

s-The string to output 
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STSFlushlnput 

Flushes any partially entered input line from a typescript 

Call: 

Procedure STSFlushInput( 

ServPort : Typescript) 

Parameters: 

ServPort-The port for the typescript 



STSFlushOutput 
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Forces any queued output for a Typescript to be displayed on the screen. STSPutChar and STSPutString may 
not display the output characters immediately, giving strange results if one tries to use the same viewport for 
simple text output and for graphics. STSFlushOutput ensures that all Typescript output is displayed on the 
screen before it returns. 

Call: 

Procedure STSFlushOutput( 

ServPort : Typescript) 

Parameters: 

ServPort-The port for the typescript 
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STSChangeEnv 

Changes the Environment connection associated with a typescript. The Environment connection determines 
the searchlists used for Escape Completion within that typescript. 

Parameters: 

ServPort-The port for the typescript 

env-The new Environment Connection to use. 
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STSGrabWindow 

STSGrabWindow tells Typescript to stop monitoring the state of the window containing a Typescript for 
change is state, size or coveredness. A program such as the editor uses this procedure to gain control of the 
default user window to use it for graphics. When the program terminates, typescript regains control of the 
window and redisplays its contents as of the time STSGrabWindow was called; any changes that the program 
made to the window are lost. 



an: 



Parameters: 



Function STSGrabWindow( 

ServPort : Typescript; 
kPort : Port) 
: Window 



ServPort-The, port for the typescript 

kPort-k port that the user program has ownership 
rights for or that will otherwise be deallocated when the 
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program terminates. Typescript regains control of the window 
when this port is deleted. 

Returns: 

The window that the Typescript is using. 
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